@rayspec/auth-core 1.5.0

package/dist/dto.d.ts

@@ -0,0 +1,337 @@
+/**
+ * RaySpec HTTP DTOs (Zod) — the ONLY shapes that cross the public HTTP boundary. No
+ * node-oidc-provider / jose / argon2 / Drizzle type appears here; handlers translate to/from
+ * these. Mass-assignment defense: org_id / role / tenant_id are NEVER body-bindable — they are
+ * server-derived. password_hash / key_hash / token_hash NEVER appear in any response DTO.
+ *
+ * The ONE deliberate, gated secret-in-a-response exception is `TokenResponse.refreshToken`
+ * — the rotated refresh secret, returned to a NON-browser client ONLY on the
+ * operator-gated + per-request opt-in path so it can store it in OS-secure storage (precedent:
+ * `MintApiKeyResponse.plaintext`). It is never returned to a browser flow and never logged/audited.
+ */
+import { z } from 'zod';
+import { API_KEY_GRANTABLE } from './authz.js';
+/** Membership roles (owner|admin|member). */
+export declare const Role: z.ZodEnum<{
+    owner: "owner";
+    admin: "admin";
+    member: "member";
+}>;
+export type Role = z.infer<typeof Role>;
+export declare const RegisterRequest: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+    orgName: z.ZodOptional<z.ZodString>;
+    deliverRefreshTokenInBody: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type RegisterRequest = z.infer<typeof RegisterRequest>;
+export declare const LoginRequest: z.ZodObject<{
+    email: z.ZodString;
+    password: z.ZodString;
+    deliverRefreshTokenInBody: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type LoginRequest = z.infer<typeof LoginRequest>;
+/**
+ * The access-token + (optional) active-org envelope returned by login / refresh / switch.
+ *
+ * `refreshToken` is a DELIBERATE, GATED exception to the "no secret in a response DTO" rule
+ * — populated ONLY when the deployment enables `RAYSPEC_BODY_REFRESH_ENABLED`
+ * AND the request opted in (`deliverRefreshTokenInBody`), i.e. a non-browser client storing the
+ * secret in OS-secure storage. Precedent: `MintApiKeyResponse.plaintext` (a secret returned once
+ * to the client by design). The secret is short-lived, rotates every refresh, and is
+ * family-revocable; a browser flow never receives it (it never opts in), and it is never logged.
+ */
+export declare const TokenResponse: z.ZodObject<{
+    accessToken: z.ZodString;
+    tokenType: z.ZodLiteral<"Bearer">;
+    expiresIn: z.ZodNumber;
+    activeOrgId: z.ZodNullable<z.ZodString>;
+    refreshToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TokenResponse = z.infer<typeof TokenResponse>;
+/** Refresh may carry the secret in the body (desktop/CLI) instead of the cookie. */
+export declare const RefreshRequest: z.ZodObject<{
+    refreshToken: z.ZodOptional<z.ZodString>;
+    deliverRefreshTokenInBody: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type RefreshRequest = z.infer<typeof RefreshRequest>;
+export declare const MembershipView: z.ZodObject<{
+    orgId: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+}, z.core.$strip>;
+export type MembershipView = z.infer<typeof MembershipView>;
+export declare const MeResponse: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    emailVerified: z.ZodBoolean;
+    memberships: z.ZodArray<z.ZodObject<{
+        orgId: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>;
+    }, z.core.$strip>>;
+    activeOrgId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MeResponse = z.infer<typeof MeResponse>;
+export declare const CreateOrgRequest: z.ZodObject<{
+    name: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CreateOrgRequest = z.infer<typeof CreateOrgRequest>;
+export declare const OrgView: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+}, z.core.$strip>;
+export type OrgView = z.infer<typeof OrgView>;
+export declare const OrgListResponse: z.ZodObject<{
+    orgs: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type OrgListResponse = z.infer<typeof OrgListResponse>;
+/** Change a member's role within an org (owner|admin only; last-owner demotion is blocked). */
+export declare const ChangeMemberRoleRequest: z.ZodObject<{
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+}, z.core.$strip>;
+export type ChangeMemberRoleRequest = z.infer<typeof ChangeMemberRoleRequest>;
+/**
+ * Add a user to an org by email (owner-only). `org_id`/`role`/`user_id` are NEVER body-bindable —
+ * the org is the server-derived tenant and the added user always joins as a plain `member`. Only
+ * the email is client-supplied; it is normalized server-side before any lookup/write.
+ */
+export declare const AddOrgMemberRequest: z.ZodObject<{
+    email: z.ZodString;
+}, z.core.$strip>;
+export type AddOrgMemberRequest = z.infer<typeof AddOrgMemberRequest>;
+/** One member of an org (the id + email + role) — never a hash/secret. */
+export declare const OrgMemberView: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+}, z.core.$strip>;
+export type OrgMemberView = z.infer<typeof OrgMemberView>;
+/**
+ * The add-member result. `oneTimePassword` is a DELIBERATE, single-shot secret-in-a-response — it
+ * is populated ONLY when the added email had no existing user, so a fresh account is provisioned
+ * with a random initial password the operator conveys out-of-band (core has no outbound mail). It
+ * is shown EXACTLY ONCE, never stored in plaintext, and never returned again (precedent:
+ * `MintApiKeyResponse.plaintext`). Absent when an existing user was added.
+ */
+export declare const AddOrgMemberResponse: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+    oneTimePassword: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AddOrgMemberResponse = z.infer<typeof AddOrgMemberResponse>;
+export declare const OrgMemberListResponse: z.ZodObject<{
+    members: z.ZodArray<z.ZodObject<{
+        userId: z.ZodString;
+        email: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type OrgMemberListResponse = z.infer<typeof OrgMemberListResponse>;
+/**
+ * Issue an out-of-band org invite (owner-only). `org_id`/`tenant_id` are NEVER body-bindable — the
+ * org is the server-derived tenant. `email` is normalized server-side. `role` defaults to `member`.
+ * `expiresInSeconds` is an OPTIONAL requested lifetime clamped server-side to a floor/ceiling.
+ *
+ * The issue path deliberately does NOT look up whether the email has an account, so the response +
+ * timing are IDENTICAL whether or not it does — no account-existence oracle (the account-existence
+ * check happens only at redeem, performed by the invitee).
+ */
+export declare const IssueInviteRequest: z.ZodObject<{
+    email: z.ZodString;
+    role: z.ZodDefault<z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>>;
+    expiresInSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type IssueInviteRequest = z.infer<typeof IssueInviteRequest>;
+/**
+ * The issued invite. `inviteToken` is a DELIBERATE, single-shot secret-in-a-response — the opaque
+ * token is shown EXACTLY ONCE (the owner conveys it out-of-band; only its hash is stored), never
+ * returned again (precedent: `MintApiKeyResponse.plaintext`). The response carries NO account-existence
+ * signal (it is identical for any email).
+ */
+export declare const IssueInviteResponse: z.ZodObject<{
+    inviteToken: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export type IssueInviteResponse = z.infer<typeof IssueInviteResponse>;
+/**
+ * Redeem an invite (the INVITEE acts, not the owner). The org is resolved FROM the token, never a URL.
+ * `password` is REQUIRED only when the invited email has no account yet (the invitee sets their own
+ * initial credential at accept); it is IGNORED when the email already has an account (the invitee must
+ * instead be authenticated as that account — a token bearer can never set/reset an existing user's
+ * password). `password` shares the register/login shape policy.
+ */
+export declare const AcceptInviteRequest: z.ZodObject<{
+    token: z.ZodString;
+    password: z.ZodOptional<z.ZodString>;
+    deliverRefreshTokenInBody: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AcceptInviteRequest = z.infer<typeof AcceptInviteRequest>;
+/**
+ * The accept result — a token envelope scoped to the joined org (so the response is immediately
+ * usable), plus the membership. `refreshToken` is the gated+opt-in body-delivered refresh secret,
+ * present ONLY on the new-account provisioning path (the invitee is freshly logged in) when the
+ * deployment enables it; an authenticated existing-account accept receives only a fresh org-scoped
+ * access token (its refresh session is untouched).
+ */
+export declare const AcceptInviteResponse: z.ZodObject<{
+    accessToken: z.ZodString;
+    tokenType: z.ZodLiteral<"Bearer">;
+    expiresIn: z.ZodNumber;
+    activeOrgId: z.ZodString;
+    userId: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+    refreshToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AcceptInviteResponse = z.infer<typeof AcceptInviteResponse>;
+/**
+ * The known api-key scopes (closed set; intersected with requested on mint). `store:read`/
+ * `store:write` let a programmatic/agency consumer (a desktop app / automation) READ
+ * and WRITE declared-store data via an org-scoped api-key — the deployer grants the write scope
+ * EXPLICITLY at mint (it is not implicit).
+ *
+ * DERIVED from `API_KEY_GRANTABLE` (authz.ts) — the SINGLE source of truth shared with `authorize()`.
+ * This is not a parallel literal that can silently drift from the runtime gate: a scope minted here
+ * that authorize() would never grant (or vice-versa) is structurally impossible, because both read
+ * the same array. (The authz.test.ts derived-invariant test additionally pins the equality.)
+ */
+export declare const ApiKeyScope: z.ZodEnum<{ [K in (typeof API_KEY_GRANTABLE)[number]]: K; }>;
+export type ApiKeyScope = z.infer<typeof ApiKeyScope>;
+export declare const MintApiKeyRequest: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "agent:run": "agent:run";
+        "agent:read": "agent:read";
+        "store:read": "store:read";
+        "store:write": "store:write";
+        "org:read": "org:read";
+        "org:member:add": "org:member:add";
+        "org:member:change": "org:member:change";
+        "org:switch": "org:switch";
+        "apikey:read": "apikey:read";
+        "apikey:mint": "apikey:mint";
+        "apikey:revoke": "apikey:revoke";
+    }>>>;
+}, z.core.$strip>;
+export type MintApiKeyRequest = z.infer<typeof MintApiKeyRequest>;
+/** The mint response is the ONLY place plaintext is returned — ONCE. */
+export declare const MintApiKeyResponse: z.ZodObject<{
+    id: z.ZodString;
+    keyPrefix: z.ZodString;
+    plaintext: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "agent:run": "agent:run";
+        "agent:read": "agent:read";
+        "store:read": "store:read";
+        "store:write": "store:write";
+        "org:read": "org:read";
+        "org:member:add": "org:member:add";
+        "org:member:change": "org:member:change";
+        "org:switch": "org:switch";
+        "apikey:read": "apikey:read";
+        "apikey:mint": "apikey:mint";
+        "apikey:revoke": "apikey:revoke";
+    }>>;
+}, z.core.$strip>;
+export type MintApiKeyResponse = z.infer<typeof MintApiKeyResponse>;
+/**
+ * The REDACTED mint snapshot — the ONLY shape persisted in idempotency_keys.snapshot and the
+ * shape returned on an Idempotency-Key REPLAY. It NEVER carries
+ * `plaintext`: the secret is shown EXACTLY ONCE on the original mint; a retry returns only the
+ * non-secret metadata so a DB dump of the no-TTL snapshot column yields no usable `<prefix>.<secret>`
+ * credential. `replayed: true` signals the caller that the plaintext is not available again.
+ */
+export declare const MintApiKeyReplay: z.ZodObject<{
+    id: z.ZodString;
+    keyPrefix: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "agent:run": "agent:run";
+        "agent:read": "agent:read";
+        "store:read": "store:read";
+        "store:write": "store:write";
+        "org:read": "org:read";
+        "org:member:add": "org:member:add";
+        "org:member:change": "org:member:change";
+        "org:switch": "org:switch";
+        "apikey:read": "apikey:read";
+        "apikey:mint": "apikey:mint";
+        "apikey:revoke": "apikey:revoke";
+    }>>;
+    replayed: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type MintApiKeyReplay = z.infer<typeof MintApiKeyReplay>;
+/** Listing never includes plaintext or the hash. */
+export declare const ApiKeyView: z.ZodObject<{
+    id: z.ZodString;
+    keyPrefix: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    lastUsedAt: z.ZodNullable<z.ZodString>;
+    revokedAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type ApiKeyView = z.infer<typeof ApiKeyView>;
+export declare const ApiKeyListResponse: z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        keyPrefix: z.ZodString;
+        scopes: z.ZodArray<z.ZodString>;
+        lastUsedAt: z.ZodNullable<z.ZodString>;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ApiKeyListResponse = z.infer<typeof ApiKeyListResponse>;
+//# sourceMappingURL=dto.d.ts.map

package/dist/dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":"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"}

package/dist/dto.js

@@ -0,0 +1,221 @@
+/**
+ * RaySpec HTTP DTOs (Zod) — the ONLY shapes that cross the public HTTP boundary. No
+ * node-oidc-provider / jose / argon2 / Drizzle type appears here; handlers translate to/from
+ * these. Mass-assignment defense: org_id / role / tenant_id are NEVER body-bindable — they are
+ * server-derived. password_hash / key_hash / token_hash NEVER appear in any response DTO.
+ *
+ * The ONE deliberate, gated secret-in-a-response exception is `TokenResponse.refreshToken`
+ * — the rotated refresh secret, returned to a NON-browser client ONLY on the
+ * operator-gated + per-request opt-in path so it can store it in OS-secure storage (precedent:
+ * `MintApiKeyResponse.plaintext`). It is never returned to a browser flow and never logged/audited.
+ */
+import { z } from 'zod';
+import { API_KEY_GRANTABLE } from './authz.js';
+/** Membership roles (owner|admin|member). */
+export const Role = z.enum(['owner', 'admin', 'member']);
+/** Email + password are validated for SHAPE here; normalization happens in the service. */
+const passwordField = z.string().min(8).max(1024);
+const emailField = z.string().min(3).max(254);
+// ---- auth ----------------------------------------------------------------------------------
+/**
+ * A NON-browser client (desktop/CLI) opts in to receiving the rotated refresh
+ * secret in the JSON response body (so it can store it in OS-secure storage and refresh without the
+ * httpOnly cookie). Absent/false ⇒ today's behavior. Only honored when the deployment ALSO enables
+ * the operator gate (`bodyRefreshEnabled`); a browser flow never sets it. Shared by register/login/
+ * refresh.
+ */
+const deliverRefreshTokenInBody = z.boolean().optional();
+export const RegisterRequest = z.object({
+    email: emailField,
+    password: passwordField,
+    /** Optional: auto-create an org + owner membership for the new user. */
+    orgName: z.string().min(1).max(200).optional(),
+    deliverRefreshTokenInBody,
+});
+export const LoginRequest = z.object({
+    email: emailField,
+    password: passwordField,
+    deliverRefreshTokenInBody,
+});
+/**
+ * The access-token + (optional) active-org envelope returned by login / refresh / switch.
+ *
+ * `refreshToken` is a DELIBERATE, GATED exception to the "no secret in a response DTO" rule
+ * — populated ONLY when the deployment enables `RAYSPEC_BODY_REFRESH_ENABLED`
+ * AND the request opted in (`deliverRefreshTokenInBody`), i.e. a non-browser client storing the
+ * secret in OS-secure storage. Precedent: `MintApiKeyResponse.plaintext` (a secret returned once
+ * to the client by design). The secret is short-lived, rotates every refresh, and is
+ * family-revocable; a browser flow never receives it (it never opts in), and it is never logged.
+ */
+export const TokenResponse = z.object({
+    accessToken: z.string(),
+    tokenType: z.literal('Bearer'),
+    expiresIn: z.number().int().positive(),
+    activeOrgId: z.string().uuid().nullable(),
+    /** The rotated refresh secret — gated+opt-in only (see the type doc above). Absent otherwise. */
+    refreshToken: z.string().optional(),
+});
+/** Refresh may carry the secret in the body (desktop/CLI) instead of the cookie. */
+export const RefreshRequest = z.object({
+    refreshToken: z.string().min(1).optional(),
+    deliverRefreshTokenInBody,
+});
+export const MembershipView = z.object({
+    orgId: z.string().uuid(),
+    role: Role,
+});
+export const MeResponse = z.object({
+    userId: z.string().uuid(),
+    email: z.string(),
+    emailVerified: z.boolean(),
+    memberships: z.array(MembershipView),
+    activeOrgId: z.string().uuid().nullable(),
+});
+// ---- orgs ----------------------------------------------------------------------------------
+export const CreateOrgRequest = z.object({
+    name: z.string().min(1).max(200),
+    /** Optional slug; defaults to a normalized form of name. Lowercased + uniqueness server-side. */
+    slug: z.string().min(1).max(200).optional(),
+});
+export const OrgView = z.object({
+    id: z.string().uuid(),
+    name: z.string(),
+    slug: z.string(),
+    role: Role,
+});
+export const OrgListResponse = z.object({ orgs: z.array(OrgView) });
+/** Change a member's role within an org (owner|admin only; last-owner demotion is blocked). */
+export const ChangeMemberRoleRequest = z.object({ role: Role });
+/**
+ * Add a user to an org by email (owner-only). `org_id`/`role`/`user_id` are NEVER body-bindable —
+ * the org is the server-derived tenant and the added user always joins as a plain `member`. Only
+ * the email is client-supplied; it is normalized server-side before any lookup/write.
+ */
+export const AddOrgMemberRequest = z.object({ email: emailField });
+/** One member of an org (the id + email + role) — never a hash/secret. */
+export const OrgMemberView = z.object({
+    userId: z.string().uuid(),
+    email: z.string(),
+    role: Role,
+});
+/**
+ * The add-member result. `oneTimePassword` is a DELIBERATE, single-shot secret-in-a-response — it
+ * is populated ONLY when the added email had no existing user, so a fresh account is provisioned
+ * with a random initial password the operator conveys out-of-band (core has no outbound mail). It
+ * is shown EXACTLY ONCE, never stored in plaintext, and never returned again (precedent:
+ * `MintApiKeyResponse.plaintext`). Absent when an existing user was added.
+ */
+export const AddOrgMemberResponse = z.object({
+    userId: z.string().uuid(),
+    email: z.string(),
+    role: Role,
+    oneTimePassword: z.string().optional(),
+});
+export const OrgMemberListResponse = z.object({ members: z.array(OrgMemberView) });
+// ---- org invites (out-of-band invite-token flow) -------------------------------------------
+/**
+ * Issue an out-of-band org invite (owner-only). `org_id`/`tenant_id` are NEVER body-bindable — the
+ * org is the server-derived tenant. `email` is normalized server-side. `role` defaults to `member`.
+ * `expiresInSeconds` is an OPTIONAL requested lifetime clamped server-side to a floor/ceiling.
+ *
+ * The issue path deliberately does NOT look up whether the email has an account, so the response +
+ * timing are IDENTICAL whether or not it does — no account-existence oracle (the account-existence
+ * check happens only at redeem, performed by the invitee).
+ */
+export const IssueInviteRequest = z.object({
+    email: emailField,
+    role: Role.default('member'),
+    expiresInSeconds: z.number().int().positive().optional(),
+});
+/**
+ * The issued invite. `inviteToken` is a DELIBERATE, single-shot secret-in-a-response — the opaque
+ * token is shown EXACTLY ONCE (the owner conveys it out-of-band; only its hash is stored), never
+ * returned again (precedent: `MintApiKeyResponse.plaintext`). The response carries NO account-existence
+ * signal (it is identical for any email).
+ */
+export const IssueInviteResponse = z.object({
+    /** The opaque invite token, shown EXACTLY ONCE; never stored in plaintext, never returned again. */
+    inviteToken: z.string(),
+    email: z.string(),
+    role: Role,
+    /** The hard expiry (ISO 8601). */
+    expiresAt: z.string(),
+});
+/**
+ * Redeem an invite (the INVITEE acts, not the owner). The org is resolved FROM the token, never a URL.
+ * `password` is REQUIRED only when the invited email has no account yet (the invitee sets their own
+ * initial credential at accept); it is IGNORED when the email already has an account (the invitee must
+ * instead be authenticated as that account — a token bearer can never set/reset an existing user's
+ * password). `password` shares the register/login shape policy.
+ */
+export const AcceptInviteRequest = z.object({
+    token: z.string().min(1),
+    password: passwordField.optional(),
+    deliverRefreshTokenInBody,
+});
+/**
+ * The accept result — a token envelope scoped to the joined org (so the response is immediately
+ * usable), plus the membership. `refreshToken` is the gated+opt-in body-delivered refresh secret,
+ * present ONLY on the new-account provisioning path (the invitee is freshly logged in) when the
+ * deployment enables it; an authenticated existing-account accept receives only a fresh org-scoped
+ * access token (its refresh session is untouched).
+ */
+export const AcceptInviteResponse = z.object({
+    accessToken: z.string(),
+    tokenType: z.literal('Bearer'),
+    expiresIn: z.number().int().positive(),
+    activeOrgId: z.string().uuid(),
+    userId: z.string().uuid(),
+    role: Role,
+    /** The rotated refresh secret — gated+opt-in, new-account path only (see the type doc above). */
+    refreshToken: z.string().optional(),
+});
+// ---- api keys ------------------------------------------------------------------------------
+/**
+ * The known api-key scopes (closed set; intersected with requested on mint). `store:read`/
+ * `store:write` let a programmatic/agency consumer (a desktop app / automation) READ
+ * and WRITE declared-store data via an org-scoped api-key — the deployer grants the write scope
+ * EXPLICITLY at mint (it is not implicit).
+ *
+ * DERIVED from `API_KEY_GRANTABLE` (authz.ts) — the SINGLE source of truth shared with `authorize()`.
+ * This is not a parallel literal that can silently drift from the runtime gate: a scope minted here
+ * that authorize() would never grant (or vice-versa) is structurally impossible, because both read
+ * the same array. (The authz.test.ts derived-invariant test additionally pins the equality.)
+ */
+export const ApiKeyScope = z.enum(API_KEY_GRANTABLE);
+export const MintApiKeyRequest = z.object({
+    name: z.string().min(1).max(200).optional(),
+    scopes: z.array(ApiKeyScope).max(32).default([]),
+});
+/** The mint response is the ONLY place plaintext is returned — ONCE. */
+export const MintApiKeyResponse = z.object({
+    id: z.string().uuid(),
+    keyPrefix: z.string(),
+    /** The full plaintext key, shown EXACTLY ONCE; never stored, never returned again. */
+    plaintext: z.string(),
+    scopes: z.array(ApiKeyScope),
+});
+/**
+ * The REDACTED mint snapshot — the ONLY shape persisted in idempotency_keys.snapshot and the
+ * shape returned on an Idempotency-Key REPLAY. It NEVER carries
+ * `plaintext`: the secret is shown EXACTLY ONCE on the original mint; a retry returns only the
+ * non-secret metadata so a DB dump of the no-TTL snapshot column yields no usable `<prefix>.<secret>`
+ * credential. `replayed: true` signals the caller that the plaintext is not available again.
+ */
+export const MintApiKeyReplay = z.object({
+    id: z.string().uuid(),
+    keyPrefix: z.string(),
+    scopes: z.array(ApiKeyScope),
+    replayed: z.literal(true),
+});
+/** Listing never includes plaintext or the hash. */
+export const ApiKeyView = z.object({
+    id: z.string().uuid(),
+    keyPrefix: z.string(),
+    scopes: z.array(z.string()),
+    lastUsedAt: z.string().nullable(),
+    revokedAt: z.string().nullable(),
+    createdAt: z.string(),
+});
+export const ApiKeyListResponse = z.object({ keys: z.array(ApiKeyView) });
+//# sourceMappingURL=dto.js.map

package/dist/dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../src/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,6CAA6C;AAC7C,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGzD,2FAA2F;AAC3F,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAClD,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAE9C,+FAA+F;AAE/F;;;;;;GAMG;AACH,MAAM,yBAAyB,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC;AAEzD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,KAAK,EAAE,UAAU;IACjB,QAAQ,EAAE,aAAa;IACvB,wEAAwE;IACxE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC9C,yBAAyB;CAC1B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,KAAK,EAAE,UAAU;IACjB,QAAQ,EAAE,aAAa;IACvB,yBAAyB;CAC1B,CAAC,CAAC;AAGH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACtC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IACzC,iGAAiG;IACjG,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAGH,oFAAoF;AACpF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,yBAAyB;CAC1B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACxB,IAAI,EAAE,IAAI;CACX,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACzB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE;IAC1B,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAGH,+FAA+F;AAE/F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,iGAAiG;IACjG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CAC5C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,IAAI;CACX,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAGpE,+FAA+F;AAC/F,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAGhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;AAGnE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACzB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,IAAI;CACX,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACzB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,IAAI;IACV,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;AAGnF,+FAA+F;AAE/F;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC5B,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAC;AAGH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,oGAAoG;IACpG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,IAAI;IACV,kCAAkC;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE;IAClC,yBAAyB;CAC1B,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACtC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACzB,IAAI,EAAE,IAAI;IACV,iGAAiG;IACjG,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAGH,+FAA+F;AAE/F;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,CAC/B,iBAAqD,CACS,CAAC;AAGjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC3C,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACjD,CAAC,CAAC;AAGH,wEAAwE;AACxE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,sFAAsF;IACtF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;CAC7B,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;IAC5B,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;CAC1B,CAAC,CAAC;AAGH,oDAAoD;AACpD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC"}

package/dist/email.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Email normalization — applied BEFORE every users.email write so the partial unique index on
+ * lower(email) cannot be bypassed by compatibility/whitespace/invisible-character variants, and
+ * the dummy-hash enumeration defense operates on a single canonical form.
+ *
+ * Steps: trim, Unicode NFKC fold, lowercase, cap at 254 chars (RFC 5321), then reject any
+ * embedded Unicode Control/Format (\p{C}) or Separator/whitespace (\p{Z}) character anywhere in
+ * the address. NOT a deliverability validator — a normalization + basic shape guard. Throws on
+ * a structurally invalid address so a bad value never reaches the DB.
+ *
+ * SCOPE / LIMITATION (honest): NFKC collapses COMPATIBILITY variants (e.g. fullwidth ＡＬＩＣＥ ->
+ * alice) and the \p{C}/\p{Z}/\p{Default_Ignorable_Code_Point} reject closes the invisible-character
+ * class (zero-width space/joiner/non-joiner, word-joiner, soft-hyphen, BOM, LRM/RLO bidi marks,
+ * NBSP, AND the Default_Ignorable code points \p{C} misses — variation selectors U+FE00–FE0F /
+ * U+E0100–E01EF, Mongolian free variation selectors, etc., which are category Mn/format-invisible
+ * and would otherwise survive NFKC) — these all PASSED the previous ASCII-only guard and the
+ * earlier \p{C}/\p{Z}-only guard. It does NOT defend against cross-script HOMOGLYPHS: a Cyrillic
+ * "а" (U+0430) is a distinct letter that NFKC does not fold and \p{C}/\p{Z} does not catch, so
+ * "аlice@x.com" and "alice@x.com" remain different canonical strings. Full TR39 confusable-
+ * skeleton / IDNA defense is deliberately out of scope (it needs a confusables table);
+ * the homograph test below documents this boundary so the limitation is explicit, not implied.
+ */
+export declare function normalizeEmail(raw: string): string;
+//# sourceMappingURL=email.d.ts.map

package/dist/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD"}

package/dist/email.js

@@ -0,0 +1,46 @@
+/**
+ * Email normalization — applied BEFORE every users.email write so the partial unique index on
+ * lower(email) cannot be bypassed by compatibility/whitespace/invisible-character variants, and
+ * the dummy-hash enumeration defense operates on a single canonical form.
+ *
+ * Steps: trim, Unicode NFKC fold, lowercase, cap at 254 chars (RFC 5321), then reject any
+ * embedded Unicode Control/Format (\p{C}) or Separator/whitespace (\p{Z}) character anywhere in
+ * the address. NOT a deliverability validator — a normalization + basic shape guard. Throws on
+ * a structurally invalid address so a bad value never reaches the DB.
+ *
+ * SCOPE / LIMITATION (honest): NFKC collapses COMPATIBILITY variants (e.g. fullwidth ＡＬＩＣＥ ->
+ * alice) and the \p{C}/\p{Z}/\p{Default_Ignorable_Code_Point} reject closes the invisible-character
+ * class (zero-width space/joiner/non-joiner, word-joiner, soft-hyphen, BOM, LRM/RLO bidi marks,
+ * NBSP, AND the Default_Ignorable code points \p{C} misses — variation selectors U+FE00–FE0F /
+ * U+E0100–E01EF, Mongolian free variation selectors, etc., which are category Mn/format-invisible
+ * and would otherwise survive NFKC) — these all PASSED the previous ASCII-only guard and the
+ * earlier \p{C}/\p{Z}-only guard. It does NOT defend against cross-script HOMOGLYPHS: a Cyrillic
+ * "а" (U+0430) is a distinct letter that NFKC does not fold and \p{C}/\p{Z} does not catch, so
+ * "аlice@x.com" and "alice@x.com" remain different canonical strings. Full TR39 confusable-
+ * skeleton / IDNA defense is deliberately out of scope (it needs a confusables table);
+ * the homograph test below documents this boundary so the limitation is explicit, not implied.
+ */
+// Reject Unicode Control/Format chars (\p{C} — incl. zero-width/format/bidi marks), any
+// Separator/whitespace (\p{Z} + ASCII control/whitespace via \s), AND every other
+// Default_Ignorable code point — notably the variation selectors U+FE00–FE0F and U+E0100–E01EF,
+// which are category Mn (a Mark, NOT \p{C}) yet render invisibly and survive NFKC, so a
+// \p{C}/\p{Z}-only guard let them through and they could defeat the lower(email) unique index.
+// NFKC keeps all of these (it does not strip them), so they must be rejected explicitly. The /u
+// flag is required for \p{...}. Built so the source carries no literal invisible bytes.
+const DISALLOWED = /[\p{C}\p{Z}\p{Default_Ignorable_Code_Point}\s]/u;
+export function normalizeEmail(raw) {
+    const normalized = raw.trim().normalize('NFKC').toLowerCase();
+    if (normalized.length === 0)
+        throw new Error('email is empty');
+    if (normalized.length > 254)
+        throw new Error('email exceeds 254 characters');
+    if (DISALLOWED.test(normalized)) {
+        throw new Error('email contains control, whitespace, or invisible characters');
+    }
+    const at = normalized.indexOf('@');
+    if (at <= 0 || at !== normalized.lastIndexOf('@') || at === normalized.length - 1) {
+        throw new Error('email is not a valid address');
+    }
+    return normalized;
+}
+//# sourceMappingURL=email.js.map

package/dist/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../src/email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wFAAwF;AACxF,kFAAkF;AAClF,gGAAgG;AAChG,wFAAwF;AACxF,+FAA+F;AAC/F,gGAAgG;AAChG,wFAAwF;AACxF,MAAM,UAAU,GAAG,iDAAiD,CAAC;AAErE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAC/D,IAAI,UAAU,CAAC,MAAM,GAAG,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAC7E,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}