// ---------------------------------------------------------------------------
// Provider-neutral identity seam — the ONE auth surface the executor API runs
// on. Cloud (WorkOS api-key + sealed-session) and self-host (Better Auth) each
// supply an `IdentityProvider` Layer; the shared `ExecutionStackMiddleware`
// (see `./execution-stack-middleware.ts`) consumes only this tag, never a
// provider's native session shape. Handlers depend only on `AuthContext`.
//
// Single source of truth promoted out of the two apps:
//   - `Principal`        — the neutral resolved identity (self-host's shape is
//                          the model: org name + roles; cloud passes `roles: []`
//                          and an empty email on the api-key path).
//   - `AuthContext`      — the one Context.Service handlers read (carries roles;
//                          cloud's old tag lacked them, forward-compatible).
//   - `Unauthorized` /   — the shared error set (httpApiStatus 401 / 403 / 503),
//     `NoOrganization` /   shared by every consumer in both apps. Self-host only
//     `Unavailable`        ever produces the first two; cloud also produces
//                          `Unavailable` (503) when api-key validation is down.
//   - `IdentityProvider` — the swap seam: `authenticate(request) =>
//                          Effect<Principal, Unauthorized | NoOrganization |
//                          Unavailable>`.
// ---------------------------------------------------------------------------

import { Context, Effect, Schema } from "effect";

/**
 * The provider-neutral resolved identity. Both self-host's AuthProvider impls
 * (single-admin, Better Auth) and cloud's WorkOS path produce this. Self-host's
 * original `Principal` is the model — it carries `organizationName` (cloud's
 * resolver already yielded it) AND `roles` (cloud supplies `[]`).
 */
interface PrincipalBase {
  /** Discriminant of {@link ResolvedPrincipal}: an acting member, as opposed
   *  to the org-level `"platform"` credential. Required so every construction
   *  site declares which arm it is, and the union matches on a literal tag
   *  instead of probing for a property's presence. */
  readonly kind: "member";
  readonly accountId: string;
  readonly organizationId: string;
  readonly organizationName: string;
  /**
   * The org's URL slug (`acme`), when the resolver has it. Optional because not
   * every principal source carries it (api-key paths that never load the org
   * row). Threaded into browser-handoff URLs so they open the right org's
   * console; a missing slug just falls back to a bare, client-canonicalized URL.
   */
  readonly organizationSlug?: string;
  readonly email: string;
  readonly name: string | null;
  readonly avatarUrl: string | null;
  readonly roles: readonly string[];
}

/**
 * The provider-neutral resolved member identity. The role-model discriminant
 * makes it impossible for a role-less host to carry an authorizing org role.
 */
export type Principal = PrincipalBase &
  (
    | {
        readonly orgRoleModel: "organization";
        /**
         * The member's NORMALIZED workspace role for an `"organization"` model:
         * `"admin"` may configure workspace-level state (org-owned rows, the
         * integration catalog), `"member"` may only use it. Cloud maps its WorkOS
         * membership role (`admin` / `member`); self-host maps Better Auth's org
         * membership role (`owner` and `admin` → `"admin"`). It may be absent only
         * at a legacy serialized boundary; an organization role model then denies
         * workspace writes. A host without roles declares `orgRoleModel: "none"`.
         */
        readonly orgRole?: "admin" | "member";
      }
    | {
        readonly orgRoleModel: "none";
        readonly orgRole?: never;
      }
  );

/**
 * An ORG-level credential (cloud's org-scoped API key), resolved. Deliberately
 * NOT a `Principal`: a `Principal` names an acting member, and this credential
 * has none — mirroring the resolution layer's own split (`ApiKeyOwner` keeps
 * `accountId: string | null` for the same reason). Keeping it a separate shape
 * means no code path can accidentally bind an org credential to a subject; the
 * middleware routes it to the subject-less platform executor instead, and
 * refuses every non-read method before a handler ever runs.
 *
 * Self-host and local never produce this: their credentials always name a
 * member. It exists on the NEUTRAL seam so the shared middleware owns the
 * platform branch once, instead of each host reinventing it.
 */
export interface PlatformPrincipal {
  readonly kind: "platform";
  readonly organizationId: string;
  readonly organizationName: string;
  /** See {@link Principal.organizationSlug}. */
  readonly organizationSlug?: string;
  /** The credential's own id, for audit trails — never an acting member. */
  readonly keyId: string;
}

/** What `authenticate` resolves: an acting member, or the org-level platform
 *  credential. */
export type ResolvedPrincipal = Principal | PlatformPrincipal;

export const isPlatformPrincipal = (value: ResolvedPrincipal): value is PlatformPrincipal =>
  value.kind === "platform";

/**
 * The single `AuthContext` every executor-API handler reads. The roles-bearing
 * tag from self-host is the model; cloud now provides `roles: []` on it, which
 * is forward-compatible (cloud handlers never read roles today).
 *
 * `accountId` and `email` are `null` for an org-level platform credential —
 * there is no acting member behind it. Nullable rather than sentinel-valued so
 * any handler that needs a member has to say so (and refuse), instead of
 * silently acting as a user that does not exist. (`email: ""` on the member
 * api-key path is the pre-existing "member with no resolved email" value and
 * unrelated to this.)
 */
export class AuthContext extends Context.Service<
  AuthContext,
  {
    readonly accountId: string | null;
    readonly organizationId: string;
    readonly email: string | null;
    readonly name: string | null;
    readonly avatarUrl: string | null;
    readonly roles: readonly string[];
  }
>()("@executor-js/api/AuthContext") {}

/** Build the shared `AuthContext` value from a resolved `Principal`. */
export const authContextFromPrincipal = (principal: Principal): AuthContext["Service"] => ({
  accountId: principal.accountId,
  organizationId: principal.organizationId,
  email: principal.email,
  name: principal.name,
  avatarUrl: principal.avatarUrl,
  roles: principal.roles,
});

/** The platform credential's `AuthContext`: org identity, no member fields. */
export const authContextFromPlatform = (principal: PlatformPrincipal): AuthContext["Service"] => ({
  accountId: null,
  organizationId: principal.organizationId,
  email: null,
  name: null,
  avatarUrl: null,
  roles: [],
});

// Optional per-failure render hints. Self-host produces the bare error (these
// stay `undefined`) and its text strategy renders a generic body. Cloud fills
// `code` + `message` so its failure strategy can reproduce the exact
// `{ error, code }` JSON bytes its old `HttpResponseError` paths emitted. The
// status is fixed by the tag (401 / 403 / 503), so it is not carried as a field.
const renderHints = {
  /** Machine-readable failure code (cloud's `{ code }` body field). */
  code: Schema.optional(Schema.String),
  /** Human-readable message (cloud's `{ error }` body field). */
  message: Schema.optional(Schema.String),
} as const;

/** Authenticated but not authorized — no valid credential. Renders 401. */
export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
  "Unauthorized",
  renderHints,
  { httpApiStatus: 401 },
) {}

/** Valid credential, but the principal belongs to no organization. Renders 403. */
export class NoOrganization extends Schema.TaggedErrorClass<NoOrganization>()(
  "NoOrganization",
  renderHints,
  { httpApiStatus: 403 },
) {}

/**
 * The credential could not be validated for a transient reason (cloud's api-key
 * validation backend is down). Renders 503 — the caller should retry. Self-host
 * never produces this; it is part of the shared set so cloud provides the SAME
 * neutral `IdentityProvider` tag without a wider error channel.
 */
export class Unavailable extends Schema.TaggedErrorClass<Unavailable>()(
  "Unavailable",
  renderHints,
  { httpApiStatus: 503 },
) {}

/**
 * A valid PLATFORM credential (org-scoped API key) attempted something only an
 * acting member can do: a write on the product plane, or any request on a host
 * that serves no platform view (local's fixed executor). Renders 403.
 *
 * Its own tag rather than a reuse of `NoOrganization`: the caller DID present a
 * valid credential of a known org — telling them "no organization" would send
 * them debugging the wrong thing. The message names the actual constraint.
 */
export class ReadOnlyCredential extends Schema.TaggedErrorClass<ReadOnlyCredential>()(
  "ReadOnlyCredential",
  renderHints,
  { httpApiStatus: 403 },
) {}

/**
 * The swap seam. Resolves an incoming request to a `Principal`. WorkOS (cloud)
 * and Better Auth (self-host) are interchangeable implementations; nothing
 * downstream knows which is wired.
 *
 *   - succeeds with a `Principal`   -> authenticated
 *   - fails `Unauthorized`          -> no/invalid credential (renders 401)
 *   - fails `NoOrganization`        -> valid credential, no org (renders 403)
 *   - fails `Unavailable`           -> transient validation outage (renders 503;
 *                                      cloud only — self-host never produces it)
 *
 * Adapter-specific credential precedence (cloud's Bearer-api-key-beats-sealed-
 * session, self-host's cookie/bearer/x-api-key cascade) stays INSIDE each impl.
 * Adapter infra defects (cloud's WorkOS / user-store failures) are `Effect.die`d
 * INSIDE the impl so they surface as 500 defects, never as this error channel.
 */
export type IdentityFailure = Unauthorized | NoOrganization | Unavailable | ReadOnlyCredential;

export interface IdentityProviderShape {
  readonly authenticate: (request: Request) => Effect.Effect<ResolvedPrincipal, IdentityFailure>;
}

export class IdentityProvider extends Context.Service<IdentityProvider, IdentityProviderShape>()(
  "@executor-js/api/IdentityProvider",
) {}