@fabrika/iam-contract 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/iam-contract",
-	"version": "0.3.2",
+	"version": "0.4.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -24,7 +24,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@fabrika/app": "^0.3.2",
-		"@fabrika/auth-core": "^0.3.2"
+		"@fabrika/app": "^0.4.0",
+		"@fabrika/auth-core": "^0.4.0"
 	}
 }

package/src/index.ts

@@ -9,7 +9,20 @@
 // where they fit. Keep these clean and complete: they are the admin API contract.
 
 import type { RpcProcedureContract } from '@fabrika/app'
-import type { AppActionDef, AppSchema, AppScopeDef, PermissionEntry, PermissionSource, PrincipalType, RoleDef } from '@fabrika/auth-core'
+import type {
+	AppActionDef,
+	AppDelegationDef,
+	AppLinkMountDef,
+	AppMemberItem,
+	AppSchema,
+	AppScopeDef,
+	Locale,
+	PermissionEntry,
+	PermissionSource,
+	PrincipalAffiliation,
+	PrincipalType,
+	RoleDef,
+} from '@fabrika/auth-core'
 
 // ── Common wrappers ───────────────────────────────────────────────────────────
 
@@ -39,6 +52,8 @@ export interface PrincipalListItem {
 	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
 }
 
@@ -63,6 +78,8 @@ export interface GrantDto {
 }
 
 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[]
@@ -76,6 +93,8 @@ export interface PrincipalDetail extends PrincipalListItem {
 
 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 {
@@ -156,6 +175,18 @@ export interface AppSchemaDto {
 	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'
 }
 
 // ── Policies (origin='custom' roles, admin-composed) ──────────────────────────
@@ -253,7 +284,8 @@ export interface IssueShareLinkRequest {
 	/** Each grant is delegation-checked against the issuer on its `scope` (omitted → global). */
 	grants: { action: string; scope?: { type: string; value: string } | null }[]
 	label?: string
-	expiresAt?: number
+	/** 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. */
@@ -283,11 +315,14 @@ export interface AuthLogDto {
 	id: number
 	requestId: string
 	app: string
-	kind: 'authenticate'
+	/** 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
 }
 
@@ -335,8 +370,9 @@ export interface RotateApiKeyInput extends ApiKeyIdInput {
 	expiresAt?: number | null
 }
 
+/** Every procedure that names a principal keys it as `principalId`; a bare `id` names some other resource. */
 export interface PrincipalIdInput {
-	id: string
+	principalId: string
 }
 
 export interface ListSessionsInput extends PageInput {
@@ -432,6 +468,127 @@ export interface ListAuthLogInput {
 type RpcProcedure<TInput, TOutput> = RpcProcedureContract<TInput, TOutput>
 
 /** Browser-safe typed contract for the IAM administration API. */
+// ── Workload keys (Control's reconcile of jobs and webhooks) ──────────────────
+
+/**
+ * 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
+	/** `app` is the connector of the application named `name`, which consumes an export of `app`. */
+	kind: 'job' | 'webhook' | 'app'
+	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: 'job' | 'webhook' | 'app'
+	name: string
+}
+
+export interface RevokeWorkloadKeysResponse {
+	revoked: number
+}
+
+// ── Membership transport keys (Control's reconcile of applications without an IAM binding) ──
+
+/**
+ * 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's own people, administered by its own administrator ───────
+
+/**
+ * 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: {
@@ -439,6 +596,11 @@ export interface IamAdminRpcContract {
 		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
@@ -455,6 +617,7 @@ export interface IamAdminRpcContract {
 		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>
 	}
@@ -478,6 +641,13 @@ export interface IamAdminRpcContract {
 		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>
@@ -487,6 +657,17 @@ export interface IamAdminRpcContract {
 		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, AppSchema, AppScopeDef, PermissionEntry, PermissionSource, PrincipalType, RoleDef }
+export type { AppActionDef, AppMemberItem, AppSchema, AppScopeDef, PermissionEntry, PermissionSource, PrincipalAffiliation, PrincipalType, RoleDef }
+export * from './oauth'

package/src/oauth.ts

@@ -0,0 +1,275 @@
+import { isCimdClientId, isOAuthResourceUri, parseOAuthScopes } from '@fabrika/auth-core'
+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[]
+}
+
+export interface OAuthClientMetadataDocument {
+	client_id: string
+	client_name?: string
+	redirect_uris: string[]
+	token_endpoint_auth_method: 'none'
+	grant_types: ('authorization_code' | 'refresh_token')[]
+	response_types: ['code']
+}
+
+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']
+	client_id_metadata_document_supported: true
+}
+
+function isNonemptyText(value: unknown): value is string {
+	return typeof value === 'string' && value.length > 0
+}
+
+function field(value: unknown, name: string): unknown {
+	return typeof value === 'object' && value !== null && Object.hasOwn(value, name) ? Reflect.get(value, name) : undefined
+}
+
+function redirectUris(value: unknown): string[] | null {
+	if (!Array.isArray(value) || value.length === 0 || value.length > 32) return null
+	const uris: string[] = []
+	for (const item of value) {
+		if (!isOAuthResourceUri(item) || uris.includes(item)) return null
+		uris.push(item)
+	}
+	return uris
+}
+
+export function parseOAuthManagedClient(value: unknown): OAuthManagedClient | null {
+	const provider = field(value, 'provider')
+	const clientId = field(value, 'clientId')
+	const uris = redirectUris(field(value, 'redirectUris'))
+	return (provider === 'chatgpt' || provider === 'claude') && isCimdClientId(clientId) && uris !== null
+		? { provider, clientId, redirectUris: uris }
+		: null
+}
+
+/** A fetched document cannot enlarge the managed registration's exact redirect allowlist. */
+export function parseOAuthClientMetadata(value: unknown, registration: OAuthManagedClient): OAuthClientMetadataDocument | null {
+	const managed = parseOAuthManagedClient(registration)
+	const clientId = field(value, 'client_id')
+	const clientName = field(value, 'client_name')
+	const uris = redirectUris(field(value, 'redirect_uris'))
+	const grants = parseClientGrantTypes(field(value, 'grant_types'))
+	const rawResponses = field(value, 'response_types')
+	const responses = rawResponses === undefined ? ['code'] : rawResponses
+	if (
+		managed === null || clientId !== managed.clientId || uris === null || !uris.every((uri) => managed.redirectUris.includes(uri))
+		|| field(value, 'token_endpoint_auth_method') !== 'none' || (clientName !== undefined && !isNonemptyText(clientName))
+		|| field(value, 'client_secret') !== undefined || field(value, 'client_secret_expires_at') !== undefined || grants === null
+		|| !Array.isArray(responses) || responses.length !== 1 || responses[0] !== 'code'
+	) return null
+	const metadata: OAuthClientMetadataDocument = {
+		client_id: managed.clientId,
+		redirect_uris: uris,
+		token_endpoint_auth_method: 'none',
+		grant_types: grants,
+		response_types: ['code'],
+	}
+	if (isNonemptyText(clientName)) metadata.client_name = clientName
+	return metadata
+}
+
+function parseClientGrantTypes(value: unknown): OAuthClientMetadataDocument['grant_types'] | null {
+	if (value === undefined) return ['authorization_code']
+	if (!Array.isArray(value) || value.length === 0 || value.length > 2) return null
+	const grants: OAuthClientMetadataDocument['grant_types'] = []
+	for (const grant of value) {
+		if ((grant !== 'authorization_code' && grant !== 'refresh_token') || grants.includes(grant)) return null
+		grants.push(grant)
+	}
+	return grants.includes('authorization_code') ? grants : null
+}
+
+export function parseOAuthResourceDto(value: unknown): OAuthResourceDto | null {
+	const app = field(value, 'app')
+	const resource = field(value, 'resource')
+	const rawGrants = field(value, 'scopeGrants')
+	const rawDefaultScopes = field(value, 'defaultScopes')
+	if (
+		!isNonemptyText(app) || app.includes('*') || !isOAuthResourceUri(resource) || !Array.isArray(rawGrants) || rawGrants.length === 0
+		|| rawGrants.length > 64
+	) return null
+	const scopeGrants: OAuthResourceDto['scopeGrants'] = []
+	for (const entry of rawGrants) {
+		const scope = field(entry, 'scope')
+		const permissions = parseResourcePermissions(field(entry, 'permissions'))
+		if (typeof scope !== 'string' || parseOAuthScopes([scope]) === null || permissions === null || scopeGrants.some((grant) => grant.scope === scope)) {
+			return null
+		}
+		scopeGrants.push({ scope, permissions })
+	}
+	const dto: OAuthResourceDto = { app, resource, scopeGrants }
+	if (rawDefaultScopes !== undefined) {
+		const defaultScopes = parseOAuthScopes(rawDefaultScopes)
+		if (defaultScopes === null || !defaultScopes.every((scope) => scopeGrants.some((grant) => grant.scope === scope))) return null
+		dto.defaultScopes = defaultScopes
+	}
+	return dto
+}
+
+function parseResourcePermissions(value: unknown): KeyGrant[] | null {
+	if (!Array.isArray(value) || value.length === 0 || value.length > 64) return null
+	const permissions: KeyGrant[] = []
+	for (const entry of value) {
+		const action = field(entry, 'action')
+		const rawScope = field(entry, 'scope')
+		if (!isNonemptyText(action)) return null
+		if (rawScope === undefined) permissions.push({ action })
+		else if (rawScope === null) permissions.push({ action, scope: null })
+		else {
+			const type = field(rawScope, 'type')
+			const scopeValue = field(rawScope, 'value')
+			if (!isNonemptyText(type) || !isNonemptyText(scopeValue)) return null
+			permissions.push({ action, scope: { type, value: scopeValue } })
+		}
+	}
+	return permissions
+}
+
+export function resolveOAuthAuthorizationScopes(scope: string | undefined, resource: OAuthResourceDto): string[] | null {
+	const scopes = scope === undefined ? resource.defaultScopes : parseOAuthScopes(scope.split(' '))
+	if (!scopes || scopes.length === 0) return null
+	return scopes.every((entry) => resource.scopeGrants.some((grant) => grant.scope === entry))
+		? [...scopes]
+		: null
+}
+
+export function parseOAuthAuthorizationAttempt(value: unknown): OAuthAuthorizationParseResult {
+	const clientId = field(value, 'client_id')
+	const redirectUri = field(value, 'redirect_uri')
+	const resource = field(value, 'resource')
+	const scope = field(value, 'scope')
+	const state = field(value, 'state')
+	const challenge = field(value, 'code_challenge')
+	if (
+		field(value, 'response_type') !== 'code' || field(value, 'code_challenge_method') !== 'S256' || !isCimdClientId(clientId)
+		|| !isOAuthResourceUri(redirectUri) || !isOAuthResourceUri(resource)
+		|| (state !== undefined && (typeof state !== 'string' || state.length > 2048)) || typeof challenge !== 'string'
+		|| !/^[A-Za-z0-9_-]{43}$/.test(challenge)
+	) return { kind: 'invalid_request' }
+	if (scope !== undefined && typeof scope !== 'string') return { kind: 'invalid_request' }
+	const coordinates: OAuthAuthorizationCoordinates = {
+		response_type: 'code',
+		client_id: clientId,
+		redirect_uri: redirectUri,
+		resource,
+		code_challenge: challenge,
+		code_challenge_method: 'S256',
+	}
+	if (typeof state === 'string') coordinates.state = state
+	if (typeof scope === 'string' && parseOAuthScopes(scope.split(' ')) === null) return { kind: 'invalid_scope', coordinates, rawScope: scope }
+	const request: OAuthAuthorizationRequest = { ...coordinates }
+	if (typeof scope === 'string') request.scope = scope
+	return { kind: 'valid', request }
+}
+
+export function parseOAuthAuthorizationRequest(value: unknown): OAuthAuthorizationRequest | null {
+	const result = parseOAuthAuthorizationAttempt(value)
+	return result.kind === 'valid' ? result.request : null
+}
+
+export function parseOAuthTokenRequest(value: unknown): OAuthTokenRequest | null {
+	const clientId = field(value, 'client_id')
+	const resource = field(value, 'resource')
+	const grantType = field(value, 'grant_type')
+	if (!isCimdClientId(clientId) || !isOAuthResourceUri(resource)) return null
+	if (grantType === 'authorization_code') {
+		const code = field(value, 'code')
+		const redirectUri = field(value, 'redirect_uri')
+		const verifier = field(value, 'code_verifier')
+		if (!isNonemptyText(code) || !isOAuthResourceUri(redirectUri) || typeof verifier !== 'string' || !/^[A-Za-z0-9._~-]{43,128}$/.test(verifier)) {
+			return null
+		}
+		return { grant_type: grantType, client_id: clientId, code, redirect_uri: redirectUri, code_verifier: verifier, resource }
+	}
+	if (grantType === 'refresh_token') {
+		const refreshToken = field(value, 'refresh_token')
+		return isNonemptyText(refreshToken) ? { grant_type: grantType, client_id: clientId, refresh_token: refreshToken, resource } : null
+	}
+	return null
+}
+
+export function parseOAuthRevocationRequest(value: unknown): OAuthRevocationRequest | null {
+	const clientId = field(value, 'client_id')
+	const token = field(value, 'token')
+	const hint = field(value, 'token_type_hint')
+	if (
+		!isCimdClientId(clientId) || typeof token !== 'string' || token.length === 0 || token.length > 32768
+		|| (hint !== undefined && (typeof hint !== 'string' || hint.length > 200))
+	) return null
+	const request: OAuthRevocationRequest = { client_id: clientId, token }
+	if (hint === 'access_token' || hint === 'refresh_token') request.token_type_hint = hint
+	return request
+}