@fabrika/iam-contract 0.9.0-dev.1 → 0.9.0-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/iam-contract",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.3",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -11,12 +11,13 @@
 		"access": "public"
 	},
 	"files": [
-		"src"
+		"src",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		}
 	},
@@ -24,7 +25,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@fabrika/app": "0.9.0-dev.1",
-		"@fabrika/auth-core": "0.9.0-dev.1"
+		"@fabrika/app": "0.9.0-dev.3",
+		"@fabrika/auth-core": "0.9.0-dev.3"
 	}
 }

package/types/src/access.d.ts

@@ -0,0 +1,25 @@
+import { type AppSchema, type PermissionEntry } from '@fabrika/auth-core';
+/** Durable IAM application id of IAM itself — a deployed identity, not configuration branding (ADR-0024). */
+export declare const IAM_APP_ID = "propustka";
+export declare const IAM_ACTIONS: Readonly<{
+    /** Administer identity and access for the installation. Global only; it reaches every application. */
+    ADMIN: "iam.admin";
+    /** Manage the people of applications, never of the installation's own apps. Global, or in `app` values. */
+    USERS_MANAGE: "iam.users.manage";
+}>;
+export declare const IAM_SCOPES: Readonly<{
+    /** One application environment, by its IAM id `<app>@<env>`. */
+    APP: "app";
+}>;
+/** The preset role a user administrator holds. */
+export declare const USER_ADMIN_ROLE = "user-admin";
+/** What a holder of IAM permissions administers: the installation, or the people of some applications (`null` = all). */
+export type IamAdministrationScope = {
+    readonly kind: 'installation';
+} | {
+    readonly kind: 'users';
+    readonly apps: readonly string[] | null;
+};
+/** The administration IAM permissions confer, or null for none. IAM adds that a user administrator acts from a session. */
+export declare function iamAdministrationScope(permissions: PermissionEntry[]): IamAdministrationScope | null;
+export declare const IAM_APP_SCHEMA: AppSchema;

package/types/src/index.d.ts

@@ -0,0 +1,603 @@
+import type { RpcProcedureContract } from '@fabrika/app';
+import type { AppActionDef, AppDelegationDef, AppLinkMountDef, AppMemberItem, AppSchema, AppScopeDef, Locale, PermissionEntry, PermissionSource, PrincipalAffiliation, PrincipalType, RoleDef, WorkloadKind } from '@fabrika/auth-core';
+/** A plain list response. */
+export interface ListResponse<T> {
+    items: T[];
+}
+/**
+ * A cursor-paginated list. `nextCursor` is the opaque cursor to pass as `before`
+ * for the next page; null when there are no more rows.
+ */
+export interface CursorList<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+/** Derived principal status — invited (unclaimed) → active → disabled. */
+export type PrincipalStatus = 'invited' | 'active' | 'disabled';
+export interface PrincipalListItem {
+    id: string;
+    type: PrincipalType;
+    label: string;
+    email: string | null;
+    externalId: string | null;
+    status: PrincipalStatus;
+    /** `external`: a person from outside the organization, who holds only roles declared external (ADR-0051). */
+    affiliation: PrincipalAffiliation;
+    createdAt: number;
+}
+export interface GrantDto {
+    id: string;
+    principalId: string;
+    /** Named role/policy key; null for an inline grant (then `permissions` is set). */
+    roleKey: string | null;
+    /** Inline action-pattern set; null for a role-based grant (then `roleKey` is set). */
+    permissions: string[] | null;
+    /** Scope dimension; null = global (both rise/fall together). */
+    scopeType: string | null;
+    /** Opaque, app-owned scope value; null = global. */
+    scopeValue: string | null;
+    /** App id this grant applies to; null = all apps (cross-app). */
+    app: string | null;
+    grantedBy: string | null;
+    expiresAt: number | null;
+    createdAt: number;
+    /** True when `roleKey` is set but no longer resolves to a known role (zero perms). */
+    dangling: boolean;
+}
+export interface PrincipalDetail extends PrincipalListItem {
+    /** The mailbox is listed in `IAM_BOOTSTRAP_ADMINS`: an internal user with it is an installation admin. */
+    bootstrapMailbox: boolean;
+    grants: GrantDto[];
+    /** Effective permissions with `source` (grant / bootstrap / group:<ref>). */
+    permissions: PermissionEntry[];
+    authentication: {
+        /** OIDC is linked when this user has claimed an identity-provider subject. */
+        oidc: {
+            state: 'unavailable' | 'unlinked' | 'linked';
+        };
+        /** Password access is globally opt-in and then enabled per user. */
+        password: {
+            state: 'unavailable' | 'disabled' | 'pending' | 'enabled';
+        };
+    };
+}
+export interface InviteRequest {
+    email: string;
+    /** Omitted: `internal`. An `external` user signs in by password only, and OIDC never claims it. */
+    affiliation?: PrincipalAffiliation;
+}
+export interface UpdatePrincipalRequest {
+    disabled: boolean;
+}
+/**
+ * A browser session, as an operator sees it. Never the cookie or its hash — a session is addressed
+ * by `id`, which is not a credential.
+ */
+export interface SessionDto {
+    id: string;
+    principalId: string;
+    /** How the human proved who they were; `local_dev` is IAM's `LOCAL_DEV_LOGIN` bypass. */
+    authenticationMethod: 'oidc' | 'password' | 'local_dev';
+    /** The app this session is bound to (an ADR-0022 child); null = the IAM session itself. */
+    app: string | null;
+    /** The IAM session this was derived from; null on an IAM session. Revoking that one revokes this. */
+    parentSessionId: string | null;
+    /** `active` until it is revoked or its expiry passes. A revoked session reads `revoked`. */
+    status: 'active' | 'revoked' | 'expired';
+    createdAt: number;
+    expiresAt: number;
+    revokedAt: number | null;
+}
+export interface CreateGrantRequest {
+    principalId: string;
+    /** A named role/policy key — XOR `permissions` (supply exactly one). */
+    roleKey?: string;
+    /** An inline action-pattern set — XOR `roleKey` (supply exactly one). */
+    permissions?: string[];
+    /** Scope dimension; null / omitted = global. Both-or-neither with `scopeValue`. */
+    scopeType?: string | null;
+    /** Opaque, app-owned scope value; null / omitted = global. */
+    scopeValue?: string | null;
+    /** App id (a registered app id); null / omitted = all apps (cross-app). */
+    app?: string | null;
+    expiresAt?: number | null;
+}
+/** The set of app ids propustka knows about — the choices for a grant's `app`. */
+export interface AppDto {
+    id: string;
+    /** The name the app's schema declares for people; null when it declares none. */
+    displayName: string | null;
+    /** One of the installation's own apps (a platform audience): a user administrator grants nothing there (ADR-0058). */
+    installation: boolean;
+}
+/** A role available for the calling app — a built-in or a DB row (app/custom). */
+export interface RoleDto {
+    key: string;
+    name: string;
+    description?: string;
+    permissions: string[];
+    /** 'builtin' (cross-app, e.g. admin), 'app' (reconciled), or 'custom' (admin-made). */
+    origin: 'builtin' | 'app' | 'custom';
+}
+/**
+ * The body of `PUT /admin/apps/:app/schema` — one of the two surviving REST operations, because a
+ * deploy step reconciles an app's vocabulary from outside the installation. It IS the core
+ * `AppSchema`; `reconcileSchema` in `@fabrika/auth` sends exactly this.
+ */
+export type PutAppSchemaRequest = AppSchema;
+/** GET schema response — the app's scopes, actions, and origin='app' roles. */
+export interface AppSchemaDto {
+    app: string;
+    scopes: AppScopeDef[];
+    actions: AppActionDef[];
+    /** role_key -> def, origin='app' only (reconciled from code). */
+    roles: Record<string, RoleDef>;
+    /** Share-link mounts; absent when the app declares none. */
+    links?: Record<string, AppLinkMountDef>;
+    /** Endpoints that may spend membership authority; absent when the app declares none. */
+    delegations?: Record<string, AppDelegationDef>;
+    /** The language IAM speaks to the app's people; absent when the app declares none. */
+    locale?: Locale;
+    /** The name IAM shows for the app; absent when the app declares none. */
+    displayName?: string;
+    /** The actions that manage and list the app's own people; absent when the app declares none. */
+    members?: {
+        manage: string;
+        list: string;
+    };
+    /** `labels` when the app's directory shows labels to `members.list` holders. */
+    directory?: 'labels';
+}
+/** A custom policy (an origin='custom' role row) for an app. */
+export interface PolicyDto {
+    app: string;
+    key: string;
+    name: string;
+    description?: string;
+    permissions: string[];
+    createdAt: number;
+}
+export interface CreatePolicyRequest {
+    key: string;
+    name: string;
+    description?: string;
+    permissions: string[];
+}
+export interface UpdatePolicyRequest {
+    name: string;
+    description?: string;
+    permissions: string[];
+}
+/** Metadata view of a service-principal API key (the secret is never returned here). */
+export interface ApiKeyDto {
+    principalId: string;
+    label: string;
+    status: PrincipalStatus;
+    grants: GrantDto[];
+    createdAt: number;
+}
+/**
+ * One API key with its live credential. Its permissions are its grants, edited with `grants.create` and
+ * `grants.delete` by an installation administrator and read again at every token exchange.
+ */
+export interface ApiKeyDetail extends ApiKeyDto {
+    /** The key's live credential, or null when none is live (a revoked key). */
+    credential: ApiKeyCredentialDto | null;
+}
+export interface ApiKeyCredentialDto {
+    /** The app the key mints tokens for; null = every app. A grant at another app never reaches the key's token. */
+    app: string | null;
+    expiresAt: number | null;
+}
+export interface ProvisionApiKeyRequest {
+    label: string;
+    type: 'service';
+    /** A named role/policy key — XOR `permissions` (supply exactly one). */
+    roleKey?: string;
+    /** An inline action-pattern set — XOR `roleKey` (supply exactly one). */
+    permissions?: string[];
+    /** Scope dimension; null / omitted = global. Both-or-neither with `scopeValue`. */
+    scopeType?: string | null;
+    /** Opaque, app-owned scope value; null / omitted = global. */
+    scopeValue?: string | null;
+    /** App id (a registered app id); null / omitted = all apps. */
+    app?: string | null;
+    expiresAt?: number | null;
+}
+/**
+ * Provisioning result. `apiKey` (a `px_…` credential bound to the new service principal) is shown
+ * exactly ONCE — copy it now, it is not retrievable later. Carried as a bearer (or a declared
+ * header) directly to apps on the propustka-native path (`mintFromKey`), no Cloudflare Access in
+ * front.
+ */
+export interface ProvisionApiKeyResponse {
+    principalId: string;
+    apiKey: string;
+}
+/** Rotation result — new key shown once; principal + grants unchanged, old key stops working. */
+export interface RotateApiKeyResponse {
+    principalId: string;
+    apiKey: string;
+}
+/** Metadata only — never the token hash or plaintext. A share link is an anonymous credential. */
+export interface ShareLinkListItem {
+    id: string;
+    label: string | null;
+    /** The app this link mints for. Never null on a link issued after the app binding (SEC-2). */
+    app: string | null;
+    issuedBy: string | null;
+    expiresAt: number | null;
+    revokedAt: number | null;
+    createdAt: number;
+    /** Frozen inline grants — matched by `permits` (action + optional scope), not exact resource. */
+    grants: {
+        action: string;
+        scope: {
+            type: string;
+            value: string;
+        } | null;
+    }[];
+}
+export interface IssueShareLinkRequest {
+    /**
+     * The app the link mints for. REQUIRED: an anonymous credential's grants are frozen at issue, so
+     * the app they were delegated against is the only thing that keeps them from being spent at every
+     * other app behind the proxy.
+     */
+    app: string;
+    /** Each grant is delegation-checked against the issuer on its `scope` (omitted → global). */
+    grants: {
+        action: string;
+        scope?: {
+            type: string;
+            value: string;
+        } | null;
+    }[];
+    label?: string;
+    /** Absolute expiry (unix seconds). REQUIRED, and at most `MAX_KEY_LIFETIME_SECONDS` ahead: no key is permanent. */
+    expiresAt: number;
+}
+/** Issued share-link result — the plaintext `px_` token returned ONCE. */
+export interface IssuedShareLinkResponse {
+    id: string;
+    token: string;
+}
+export interface AuditEventDto {
+    id: string;
+    requestId: string;
+    principalId: string | null;
+    principalLabel: string;
+    credentialId: string | null;
+    app: string;
+    action: string;
+    resourceType: string;
+    resourceId: string | null;
+    diff: unknown;
+    metadata: unknown;
+    createdAt: number;
+}
+export interface AuthLogDto {
+    id: number;
+    requestId: string;
+    app: string;
+    /** A login attempt or a mint (`authenticate`), or the end of a session (`logout`). */
+    kind: 'authenticate' | 'logout';
+    principalId: string | null;
+    credentialId: string | null;
+    decision: 'allow' | 'deny';
+    reason: string | null;
+    /** The login opened a session of an installation administrator. */
+    privileged: boolean;
+    createdAt: number;
+}
+export interface MeDto {
+    id: string;
+    type: PrincipalType;
+    label: string;
+    permissions: PermissionEntry[];
+}
+export interface OkResponse {
+    ok: true;
+}
+/** Every admin list takes the same page coordinates: an opaque `before` cursor and a row `limit`. */
+export interface PageInput {
+    before?: string;
+    limit?: number;
+}
+export interface ListPrincipalsInput extends PageInput {
+    type?: PrincipalType;
+    status?: PrincipalStatus;
+    q?: string;
+}
+export type ListApiKeysInput = PageInput;
+export interface ListShareLinksInput extends PageInput {
+    /** Only links minting for this app. */
+    app?: string;
+    /** Revoked links are hidden by default; the console asks for them explicitly. */
+    includeRevoked?: boolean;
+}
+export interface RotateApiKeyInput extends ApiKeyIdInput {
+    /**
+     * New absolute expiry (unix seconds), or `null` for none. OMITTED carries the replaced
+     * credential's expiry forward — rotation replaces a secret, it does not extend a lifetime.
+     */
+    expiresAt?: number | null;
+}
+/** Every procedure that names a principal keys it as `principalId`; a bare `id` names some other resource. */
+export interface PrincipalIdInput {
+    principalId: string;
+}
+export interface ListSessionsInput extends PageInput {
+    /** Whose sessions to list. */
+    principalId: string;
+}
+export interface SessionIdInput {
+    id: string;
+}
+/** How many rows the call actually revoked; an already-revoked session is not counted again. */
+export interface RevokedSessionsResponse {
+    revoked: number;
+}
+export interface UpdatePrincipalInput extends UpdatePrincipalRequest, PrincipalIdInput {
+}
+/** Password action sent by email, or a one-time URL shown only in this response. */
+export type PasswordActionDelivery = {
+    delivery: 'email';
+    email: string;
+    expiresAt: number;
+} | {
+    delivery: 'manual';
+    url: string;
+    expiresAt: number;
+};
+export interface GrantIdInput {
+    id: string;
+}
+export interface AppInput {
+    app: string;
+}
+/**
+ * The public origins IAM will hand this app a session at (ADR-0022). Declarative: the whole set is
+ * stated, so removing one is the same call as adding one and a stale entry cannot survive a deploy.
+ */
+export interface SetReturnOriginsRequest {
+    app: string;
+    origins: string[];
+}
+export interface ReturnOriginsDto {
+    app: string;
+    /** Canonicalized: lower-cased scheme and host, default port dropped, no path. */
+    origins: string[];
+}
+export interface ListRolesInput {
+    app?: string | null;
+}
+export interface CreatePolicyInput {
+    app: string;
+    policy: CreatePolicyRequest;
+}
+export interface UpdatePolicyInput {
+    app: string;
+    key: string;
+    policy: UpdatePolicyRequest;
+}
+export interface PolicyIdInput {
+    app: string;
+    key: string;
+}
+export interface ApiKeyIdInput {
+    principalId: string;
+}
+export interface ShareLinkIdInput {
+    id: string;
+}
+export interface ListAuditInput {
+    resourceType?: string;
+    resourceId?: string;
+    principalId?: string;
+    action?: string;
+    requestId?: string;
+    before?: string;
+    limit?: number;
+}
+export interface ListAuthLogInput {
+    principalId?: string;
+    requestId?: string;
+    decision?: 'allow' | 'deny';
+    before?: string;
+    limit?: number;
+}
+type RpcProcedure<TInput, TOutput> = RpcProcedureContract<TInput, TOutput>;
+/** Browser-safe typed contract for the IAM administration API. */
+/**
+ * Issue a fresh key for one workload of an application (ADR-0022 "Principal kinds"). The key resolves to the actions
+ * the app's reconciled schema declares for the workload. Every other key of the workload is revoked except `keep`.
+ */
+export interface IssueWorkloadKeyRequest {
+    /** The IAM application id `<app>@<env>`. */
+    app: string;
+    /**
+     * `public` is a public procedure, named by its endpoint id; `app` is the connector of the application named `name`,
+     * which consumes an export of `app`.
+     */
+    kind: WorkloadKind;
+    name: string;
+    /** Absolute expiry (unix seconds), after now and at most 30 days ahead. */
+    expiresAt: number;
+    /**
+     * The credential id of the key the caller has recorded as active, which stays valid until the caller replaces it; null
+     * when it has none. A key issued earlier and never recorded is an orphan, and is revoked.
+     */
+    keep: string | null;
+}
+/** The plaintext key is returned once. */
+export interface IssueWorkloadKeyResponse {
+    key: string;
+    credentialId: string;
+    principalId: string;
+    expiresAt: number;
+}
+/**
+ * Revoke every key of one workload of `app`, the key a rotation kept included: what Control asks when a consumer stops
+ * importing from `app`. A workload with no principal has nothing to revoke.
+ */
+export interface RevokeWorkloadKeysRequest {
+    app: string;
+    kind: WorkloadKind;
+    name: string;
+}
+export interface RevokeWorkloadKeysResponse {
+    revoked: number;
+}
+/**
+ * Issue a fresh membership transport key for one application environment (ADR-0022 rule 6). The key authenticates
+ * IAM's `/membership/*` surface and pins the application id; it carries no authority. Every other key of the
+ * application environment is deleted except `keep`.
+ */
+export interface IssueMembershipKeyRequest {
+    /** The IAM application id `<app>@<env>`. */
+    app: string;
+    /** Absolute expiry (unix seconds), after now and at most 30 days ahead. */
+    expiresAt: number;
+    /** The id of the key the caller has recorded as active, which stays valid until the caller replaces it; null when it has none. */
+    keep: string | null;
+}
+/** The issued key, shown once. `id` is what a later issuance keeps. */
+export interface IssueMembershipKeyResponse {
+    key: string;
+    id: string;
+    expiresAt: number;
+}
+/**
+ * An application whose people the caller administers: it holds the application's `members.manage` globally there.
+ * `roles` are the application's global roles the caller may grant, those whose every action it holds itself.
+ */
+export interface AdministeredAppDto {
+    app: string;
+    displayName: string | null;
+    roles: {
+        key: string;
+        name: string;
+        permissions: string[];
+    }[];
+}
+export interface AppPeopleInput {
+    app: string;
+    /** The previous page's `next`. */
+    after?: string;
+}
+/** One page of the application's people, as its administrator sees them: labels, addresses and last sign-ins. */
+export interface AppPeopleDto {
+    app: string;
+    members: AppMemberItem[];
+    next: string | null;
+}
+/**
+ * Give a person who already has an IAM principal one of the application's global roles, by its address (the people
+ * list answers each person's). An address IAM knows no person for is a 404: an IAM administrator invites people, an
+ * application's administrator does not. Holding the role already answers the same.
+ */
+export interface GrantAppRoleRequest {
+    app: string;
+    role: string;
+    email: string;
+}
+export interface GrantAppRoleResponse {
+    principalId: string;
+    role: string;
+    /** False when the person held the role already. */
+    granted: boolean;
+}
+/** Remove the global grant of `role` from a person. Repeating it answers the same. */
+export interface RevokeAppRoleRequest {
+    app: string;
+    role: string;
+    principalId: string;
+}
+export interface RevokeAppRoleResponse {
+    /** False when the person held no such grant. */
+    revoked: boolean;
+}
+export interface IamAdminRpcContract {
+    me: RpcProcedure<void, MeDto>;
+    principals: {
+        list: RpcProcedure<ListPrincipalsInput, CursorList<PrincipalListItem>>;
+        get: RpcProcedure<PrincipalIdInput, PrincipalDetail>;
+        invite: RpcProcedure<InviteRequest, PrincipalListItem>;
+        update: RpcProcedure<UpdatePrincipalInput, PrincipalListItem>;
+        /**
+         * Make an external user internal, revoking its sessions and pending password actions. A bootstrap mailbox becomes
+         * an installation admin. There is no way back; promoting an internal principal is a 409.
+         */
+        promote: RpcProcedure<PrincipalIdInput, PrincipalListItem>;
+    };
+    /**
+     * Sessions an operator no longer trusts. Revoking an IAM session also ends every app session
+     * derived from it — a child is only valid while its parent is — so this is one call, not a sweep.
+     */
+    sessions: {
+        list: RpcProcedure<ListSessionsInput, CursorList<SessionDto>>;
+        revoke: RpcProcedure<SessionIdInput, RevokedSessionsResponse>;
+        revokeAll: RpcProcedure<PrincipalIdInput, RevokedSessionsResponse>;
+    };
+    passwords: {
+        issueEnrollment: RpcProcedure<PrincipalIdInput, PasswordActionDelivery>;
+        issueReset: RpcProcedure<PrincipalIdInput, PasswordActionDelivery>;
+        disable: RpcProcedure<PrincipalIdInput, OkResponse>;
+    };
+    grants: {
+        /** A role grant the principal already holds — same role, scope and app — answers 409 naming it. */
+        create: RpcProcedure<CreateGrantRequest, GrantDto>;
+        delete: RpcProcedure<GrantIdInput, OkResponse>;
+    };
+    apps: {
+        list: RpcProcedure<void, ListResponse<AppDto>>;
+        getSchema: RpcProcedure<AppInput, AppSchemaDto>;
+        setReturnOrigins: RpcProcedure<SetReturnOriginsRequest, ReturnOriginsDto>;
+    };
+    roles: {
+        list: RpcProcedure<ListRolesInput, ListResponse<RoleDto>>;
+    };
+    policies: {
+        list: RpcProcedure<AppInput, ListResponse<PolicyDto>>;
+        create: RpcProcedure<CreatePolicyInput, PolicyDto>;
+        update: RpcProcedure<UpdatePolicyInput, PolicyDto>;
+        delete: RpcProcedure<PolicyIdInput, OkResponse>;
+    };
+    apiKeys: {
+        list: RpcProcedure<ListApiKeysInput, CursorList<ApiKeyDto>>;
+        get: RpcProcedure<ApiKeyIdInput, ApiKeyDetail>;
+        provision: RpcProcedure<ProvisionApiKeyRequest, ProvisionApiKeyResponse>;
+        rotate: RpcProcedure<RotateApiKeyInput, RotateApiKeyResponse>;
+        revoke: RpcProcedure<ApiKeyIdInput, OkResponse>;
+    };
+    workloads: {
+        issueKey: RpcProcedure<IssueWorkloadKeyRequest, IssueWorkloadKeyResponse>;
+        revokeKeys: RpcProcedure<RevokeWorkloadKeysRequest, RevokeWorkloadKeysResponse>;
+    };
+    membershipKeys: {
+        issue: RpcProcedure<IssueMembershipKeyRequest, IssueMembershipKeyResponse>;
+    };
+    shareLinks: {
+        list: RpcProcedure<ListShareLinksInput, CursorList<ShareLinkListItem>>;
+        issue: RpcProcedure<IssueShareLinkRequest, IssuedShareLinkResponse>;
+        revoke: RpcProcedure<ShareLinkIdInput, OkResponse>;
+    };
+    audit: {
+        list: RpcProcedure<ListAuditInput, CursorList<AuditEventDto>>;
+        listAuthLog: RpcProcedure<ListAuthLogInput, CursorList<AuthLogDto>>;
+    };
+    /**
+     * An application's own people, administered by whoever holds the application's `members.manage` globally there: no
+     * installation admin needed. Each change writes its audit row under the application.
+     */
+    appPeople: {
+        apps: RpcProcedure<void, ListResponse<AdministeredAppDto>>;
+        list: RpcProcedure<AppPeopleInput, AppPeopleDto>;
+        grant: RpcProcedure<GrantAppRoleRequest, GrantAppRoleResponse>;
+        revoke: RpcProcedure<RevokeAppRoleRequest, RevokeAppRoleResponse>;
+    };
+}
+export type { AppActionDef, AppMemberItem, AppSchema, AppScopeDef, PermissionEntry, PermissionSource, PrincipalAffiliation, PrincipalType, RoleDef };
+export * from './access';
+export * from './oauth';

package/types/src/oauth.d.ts

@@ -0,0 +1,136 @@
+import type { KeyGrant } from '@fabrika/auth-core';
+/** Managed CIMD registrations only; public dynamic registration is not part of this contract. */
+export interface OAuthManagedClient {
+    provider: 'chatgpt' | 'claude';
+    clientId: string;
+    redirectUris: string[];
+}
+/** RFC 7523 §2.2: the `client_assertion_type` of a JWT client assertion (`private_key_jwt`). */
+export declare const OAUTH_CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/** The signing algorithms IAM verifies a client assertion with. */
+export declare const OAUTH_CLIENT_ASSERTION_ALGORITHMS: readonly ["RS256"];
+export type OAuthClientAssertionAlgorithm = (typeof OAUTH_CLIENT_ASSERTION_ALGORITHMS)[number];
+interface OAuthClientMetadataFields {
+    client_id: string;
+    client_name?: string;
+    redirect_uris: string[];
+    grant_types: ('authorization_code' | 'refresh_token')[];
+    response_types: ['code'];
+}
+/** A public client, or one that authenticates with a JWT signed by a key its document publishes. */
+export type OAuthClientMetadataDocument = (OAuthClientMetadataFields & {
+    token_endpoint_auth_method: 'none';
+}) | (OAuthClientMetadataFields & {
+    token_endpoint_auth_method: 'private_key_jwt';
+    /** HTTPS, on the client id's own origin. */
+    jwks_uri: string;
+    token_endpoint_auth_signing_alg: OAuthClientAssertionAlgorithm;
+});
+/** How a token or revocation request authenticates its client: no credential, or a JWT assertion. */
+export type OAuthClientCredential = {
+    method: 'none';
+} | {
+    method: 'private_key_jwt';
+    assertion: string;
+};
+export interface OAuthResourceDto {
+    app: string;
+    resource: string;
+    /** IAM resolves these app-owned grants; OAuth scope text alone never authorizes an action. */
+    scopeGrants: {
+        scope: string;
+        permissions: KeyGrant[];
+    }[];
+    /** Used only when scope is omitted. No configured default means invalid_scope, never all scopes. */
+    defaultScopes?: string[];
+}
+/** No access token, refresh token, hash, or authorization code appears in a grant DTO. */
+export interface OAuthGrantDto {
+    id: string;
+    principalId: string;
+    clientId: string;
+    app: string;
+    resource: string;
+    scopes: string[];
+    createdAt: number;
+    expiresAt: number;
+    revokedAt: number | null;
+}
+export interface OAuthAuthorizationRequest {
+    response_type: 'code';
+    client_id: string;
+    redirect_uri: string;
+    resource: string;
+    scope?: string;
+    state?: string;
+    code_challenge: string;
+    code_challenge_method: 'S256';
+}
+export type OAuthAuthorizationCoordinates = Omit<OAuthAuthorizationRequest, 'scope'>;
+export type OAuthAuthorizationParseResult = {
+    kind: 'valid';
+    request: OAuthAuthorizationRequest;
+} | {
+    kind: 'invalid_scope';
+    coordinates: OAuthAuthorizationCoordinates;
+    rawScope: string;
+} | {
+    kind: 'invalid_request';
+};
+export type OAuthTokenRequest = {
+    grant_type: 'authorization_code';
+    client_id: string;
+    code: string;
+    redirect_uri: string;
+    code_verifier: string;
+    resource: string;
+} | {
+    grant_type: 'refresh_token';
+    client_id: string;
+    refresh_token: string;
+    resource: string;
+};
+export interface OAuthTokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+}
+export interface OAuthRevocationRequest {
+    client_id: string;
+    token: string;
+    token_type_hint?: 'access_token' | 'refresh_token';
+}
+export interface OAuthAuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    revocation_endpoint: string;
+    jwks_uri: string;
+    response_types_supported: ['code'];
+    grant_types_supported: ['authorization_code', 'refresh_token'];
+    code_challenge_methods_supported: ['S256'];
+    token_endpoint_auth_methods_supported: ['none', 'private_key_jwt'];
+    token_endpoint_auth_signing_alg_values_supported: OAuthClientAssertionAlgorithm[];
+    revocation_endpoint_auth_methods_supported: ['none', 'private_key_jwt'];
+    revocation_endpoint_auth_signing_alg_values_supported: OAuthClientAssertionAlgorithm[];
+    /** RFC 9207: every authorization response carries `iss`. */
+    authorization_response_iss_parameter_supported: true;
+    client_id_metadata_document_supported: true;
+}
+export declare function parseOAuthManagedClient(value: unknown): OAuthManagedClient | null;
+/** A fetched document cannot enlarge the managed registration's exact redirect allowlist. */
+export declare function parseOAuthClientMetadata(value: unknown, registration: OAuthManagedClient): OAuthClientMetadataDocument | null;
+export declare function parseOAuthResourceDto(value: unknown): OAuthResourceDto | null;
+export declare function resolveOAuthAuthorizationScopes(scope: string | undefined, resource: OAuthResourceDto): string[] | null;
+export declare function parseOAuthAuthorizationAttempt(value: unknown): OAuthAuthorizationParseResult;
+export declare function parseOAuthAuthorizationRequest(value: unknown): OAuthAuthorizationRequest | null;
+export declare function parseOAuthTokenRequest(value: unknown): OAuthTokenRequest | null;
+/**
+ * The client credential of a token or revocation request (RFC 7521 §4.2). Neither assertion field is no
+ * credential; a half-present pair, another assertion type or an oversized assertion is null.
+ */
+export declare function parseOAuthClientCredential(value: unknown): OAuthClientCredential | null;
+export declare function parseOAuthRevocationRequest(value: unknown): OAuthRevocationRequest | null;
+export {};