@k9o/gate 0.0.0-stage → 1.1.0

package/src/types.ts

@@ -0,0 +1,264 @@
+/**
+ * `@k9o/gate` — public type surface.
+ *
+ * The shapes here track verbatim. End-user IDs carry the `eu_`
+ * prefix; role and group identifiers compose against the
+ * role lattice (Trust-Zone-separate `PROJECT_END_USER` for project-
+ * level end-user identities). Sessions, passkeys, MFA factors, federation
+ * links, and the rest of the Gate-managed resources receive their per-
+ * resource prefixes as the end-user table family is specified.
+ *
+ * Envelope shape (`data` + `meta`) matches; failures land via
+ * the `GateError` family per `errors.ts`, which is `KError`-compatible
+ *.
+ */
+
+/**
+ * Standard envelope. Generic over the `data` shape per function.
+ * Returned by every successful SDK call.
+ */
+export type Envelope<T> = {
+  data: T;
+  meta: Record<string, unknown>;
+};
+
+/**
+ * Project-level end-user identity (the customers OF the customer as
+ * the `PROJECT_END_USER` 7th canonical role). End-user IDs carry the
+ * `eu_<base62>` prefix.
+ */
+export type EndUser = {
+  /** `eu_<base62>` — see. */
+  id: string;
+  email: string;
+  status: "active" | "pending" | "disabled";
+  createdAt: string;
+  updatedAt: string | null;
+  lastSigninAt: string | null;
+  /** Project-level roles; `PROJECT_END_USER` is the floor membership. */
+  roles: ReadonlyArray<string>;
+  /** Project-level group memberships `_sys.end_user_groups`. */
+  groups: ReadonlyArray<string>;
+};
+
+/**
+ * Session tokens returned by sign-up / sign-in / refresh flows. Both
+ * tokens are opaque to consumers; `accessToken` carries the JWT shape
+ * for downstream Gate-aware services; `refreshToken` is opaque to the
+ * SDK consumer and is presented back to `gate.refreshToken({...})` to
+ * rotate the access token.
+ */
+export type Session = {
+  accessToken: string;
+  refreshToken: string;
+  /** ISO 8601 instant the access token expires. */
+  expiresAt: string;
+};
+
+/**
+ * Marquee sign-up / sign-in shape:
+ *   `{ user, session }`
+ */
+export type AuthResult = {
+  user: EndUser;
+  session: Session;
+};
+
+/**
+ * `gate.whoami()` shape:
+ *   `{ user }` — no fresh session is minted by `whoami` (it reflects the
+ *   caller's current session).
+ */
+export type WhoamiResult = {
+  user: EndUser;
+};
+
+/**
+ * `gate.verifySession()` shape — boolean plus the surfaced session
+ * details if valid. Returns `{ valid: false, user: null, session: null }`
+ * when the bearer session is missing or expired (no throw on invalid;
+ * throw only on transport / upstream failures).
+ */
+export type VerifySessionResult =
+  | { valid: true; user: EndUser; session: Session }
+  | { valid: false; user: null; session: null };
+
+/**
+ * Marquee request shapes. `gate.signUp` takes a CLOSED body: `{ email, password, displayName? }`.
+ * `displayName` is stored with the end user's PII (1 to 128 characters); any other field is refused by the
+ * gateway with `K9O_INVALID_FIELD_VALUE` (`context.reason: "unknown_field"`), so this type has no escape hatch.
+ */
+export type SignUpInput = {
+  email: string;
+  password: string;
+  /** Optional display name (1 to 128 characters); surfaces in account-management UI. */
+  displayName?: string;
+};
+
+export type SignInInput = {
+  email: string;
+  password: string;
+};
+
+export type SignOutInput = {
+  /**
+   * Optional refresh token to revoke. When omitted the gateway revokes
+   * the access token's bound refresh token only; explicit refresh tokens
+   * let callers revoke a specific device/session.
+   */
+  refreshToken?: string;
+};
+
+export type RefreshTokenInput = {
+  refreshToken: string;
+};
+
+/**
+ * OTP purpose — scopes the one-time code to a flow. The gateway validates
+ * against this closed set (otp.ts) and defaults to "signin" when omitted.
+ */
+export type OtpPurpose = "signin" | "magic_link" | "password_reset" | "mfa_challenge";
+
+/**
+ * `gate.passwordless.requestOtp` input — emails an OTP code to the
+ * given address. Idempotent at the per-email rate-limit ceiling per
+ * the platform anti-abuse policy.
+ */
+export type RequestOtpInput = {
+  email: string;
+  /** OTP purpose; defaults to "signin" server-side when omitted. */
+  purpose?: OtpPurpose;
+};
+
+/**
+ * `gate.passwordless.verifyOtp` input — caller supplies the OTP code
+ * received via email plus the originating email address so the
+ * gateway can resolve the right OTP row.
+ */
+export type VerifyOtpInput = {
+  email: string;
+  code: string;
+  /** Must match the `purpose` supplied to `requestOtp` (defaults "signin")
+   *  so the gateway resolves the right OTP row. */
+  purpose?: OtpPurpose;
+};
+
+/**
+ * `gate.passwordless.requestMagicLink` input — emails a magic-link
+ * token to the given address; the customer's frontend handles the
+ * post-redirect exchange via `verifyMagicLink`.
+ */
+export type RequestMagicLinkInput = {
+  email: string;
+  /**
+   * Post-redeem landing URL. When supplied it MUST exact-match an entry in
+   * the project's magic-link redirect allowlist (Gate config); a
+   * non-allowlisted value is rejected with `GATE_REDIRECT_NOT_ALLOWED` (400).
+   * Omit to use the project's configured default redirect.
+   */
+  redirectUrl?: string;
+};
+
+/**
+ * `gate.passwordless.verifyMagicLink` input — caller supplies the
+ * opaque token from the magic-link query string.
+ */
+export type VerifyMagicLinkInput = {
+  token: string;
+};
+
+/**
+ * Result of `gate.passwordless.parseMagicLinkCallback(window.location.search)`
+ * on the magic-link landing page. The gateway delivers the opaque token in the
+ * query string (`?token=…&project=…`); feed `token` to `verifyMagicLink`.
+ * Distinct from `parseSignInCallback`, which parses the SSO hash fragment.
+ */
+export type MagicLinkCallbackResult =
+  | { ok: true; token: string }
+  | { ok: false; error: string };
+
+/**
+ * JWT claim shape that `verifyJwt` resolves. Mirrors `subject.*`
+ * exposure for project-level JWTs plus the Gate-issued audience / issuer
+ * standard claims. Customer apps in Standalone mode consume this via the
+ * `verifyJwt` helper without needing the full SDK shape.
+ */
+export type GateJwtClaims = {
+  /** Issuer — the Kilimanjaro gateway base URL or project-bound issuer. */
+  iss: string;
+  /** Audience — typically the project id (`proj_<base62>`). */
+  aud: string | string[];
+  /** Subject — the end-user id (`eu_<base62>`). */
+  sub: string;
+  /** Issued-at (seconds since Unix epoch). */
+  iat: number;
+  /** Expiry (seconds since Unix epoch). */
+  exp: number;
+  /** JWT id (for revocation tracking + idempotency). */
+  jti?: string;
+  /** Project-level role array; floor is `PROJECT_END_USER`. */
+  roles?: ReadonlyArray<string>;
+  /** Project-level group memberships. */
+  groups?: ReadonlyArray<string>;
+  /** Project-level scope strings — used by `requireScope`. */
+  scopes?: ReadonlyArray<string>;
+  /** Email of the underlying end-user; convenience copy of the database column. */
+  email?: string;
+  /**
+   * Additional claims that aren't part of the canonical set. The gateway
+   * is free to embed custom claims per project policy.
+   */
+  [key: string]: unknown;
+};
+
+/**
+ * `verifyJwt` result. `valid: true` resolves to the parsed claim set;
+ * `valid: false` carries a typed reason for the failure (signature
+ * mismatch, expiry, audience mismatch, etc.) without throwing.
+ */
+export type VerifyJwtResult =
+  | { valid: true; claims: GateJwtClaims }
+  | { valid: false; reason: VerifyJwtFailure };
+
+export type VerifyJwtFailure =
+  | "INVALID_SIGNATURE"
+  | "EXPIRED"
+  | "NOT_YET_VALID"
+  | "AUDIENCE_MISMATCH"
+  | "ISSUER_MISMATCH"
+  | "MALFORMED"
+  | "ALGORITHM_NOT_ALLOWED";
+
+/**
+ * Result of `gate.parseSignInCallback(window.location.hash)` after the
+ * browser returns from an IdP-initiated sign-in. On success, carries
+ * the session tokens; on failure, carries an error subcode + description.
+ */
+export type SignInCallbackResult =
+  | {
+      ok: true;
+      accessToken: string;
+      refreshToken: string;
+      /** ISO 8601 absolute expiry timestamp for the access token. */
+      expiresAt: string;
+      /** Always "Bearer" today; reserved for future schemes. */
+      tokenType: string;
+    }
+  | {
+      ok: false;
+      /** IdpErrorSubcode ("sso_failed" | "idp_provider_not_configured" | …)
+       *  or the literal "malformed_callback" if the fragment can't be parsed. */
+      error: string;
+      errorDescription: string;
+    };
+
+/**
+ * The project's hosted sign-in page and WebAuthn relying party (`GET /@<projectSlug>/gate/hosted`). Both values come from the platform: an SDK never composes a Gate host from a slug (the label is a hash of
+ * ids the SDK does not hold).
+ */
+export type HostedGateInfo = {
+  /** Absolute hosted sign-in URL: the verified custom domain's when there is one, else the project's Gate host. */
+  signInUrl: string;
+  /** The WebAuthn relying-party id (the project's Gate host). Use it as given; never hard-code it. */
+  rpId: string;
+};