@atlasauth/backend 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -1,6 +1,44 @@
 # @atlasauth/backend changelog
 
-## Unreleased
+## 0.26.0 — 2026-10-27
+
+### Added
+
+- `iga` client resource: identity governance (access catalog, access requests and approvals, grants, delegations, separation-of-duties rules, joiner/mover/leaver lifecycle, certification campaigns).
+- `desktopMfa` client resource: the desktop login MFA policy, enrolment codes and enrolled devices (`getPolicy`, `updatePolicy`, `createEnrolmentCode`, `listDevices`, `getDevice`, `revokeDevice`, `revokeOfflineCache`, `deleteDevice`).
+- `managedGrants` client resource (`list`, `get`, `narrow`, `revoke`): the OpenID Grant Management grants each OAuth client holds for each user.
+- `leastPrivilege` client resource (`report`, `get`, `exportCsv`, and applying the narrower grants with a `dryRun` preview): what each secret key, OAuth client, MCP gateway and agent holds against what it used.
+- `mcpGateways` gains `abac` (policy checks on every tool call) and `budgets` (`list`, `create`, `get`, `update`, `delete`, `usage`).
+- `fga.settings.get` / `fga.settings.update`: the instance's FGA result-cache lifetime, default consistency mode and tuple change-log retention.
+
+- `connections.token` now caches per client until shortly before `expires_at` and takes `minTtlSeconds`; new `connections.refreshToken` (force-refresh after a provider 401, with `staleAccessToken`), `connections.tokens` (batch read of up to 100), `connections.importConnections` and `connections.exportConnections` (sealed to your public key); `connections.delete(id, { revoke: true })`. `Connection` gains `refresh_failures`, `next_refresh_at` and a typed `last_error` with the provider's code and HTTP status.
+- `connections.revoke` returns `provider_revoked`, `provider_status`, `provider_error` and `local_cleared`.
+- Webhook event types `connection.refresh_failed`, `connection.reauthorization_required`, `connection.revoked`, `connection.scopes_changed`, `connection.recovered`.
+- Connections: `setCredentials`, `rotateCredentials`, `secretVersions`, `secret` (scope `connections:secret_read`), `oauth1Sign`, `webhooks.verify` and `webhooks.*Endpoint`; `token()` takes `subject` for delegated tokens; `Connection` reports `secret_expires_at`, `previous_valid_until` and `allowed_methods`.
+- `connections` client resource: `create`, `list`, `get`, `update` (including `owner` to transfer), `delete`, `connect`, `revoke`, `token` (needs the `connections:token` scope) and `oauthClients` (`set`, `list`, `get`, `delete`), with `host_params`, `environment` and the captured token fields typed.
+- ABAC data filtering: `abac.partialEvaluate` (the policies as a filter over an unknown resource or principal, with relationship conditions resolved and optional SQL or Prisma output) and `abac.accessibleResources` (the resources a principal may act on, paged). The filter helpers `evalFilter`, `filterToSql`, `filterToPrisma` and `filterToDrizzle` are exported.
+- AuthZEN 1.0 search: `abac.authzenSearchSubject`, `authzenSearchResource` and `authzenSearchAction`.
+- ABAC authoring: `abac.templates`, `abac.links`, `abac.schema` (`get`, `set`, `delete`, `validate`), `abac.diff` and `abac.diffSources`; `abac.test` results carry `coverage`.
+- `fga.listObjects` and the resource-role `accessible` call take `limit` and `starting_after`; `listObjects` returns `has_more` and `next_cursor`.
+- `authzDecisions` client resource (`list`, `iterate`, `get`, `stats`, `settings.get/update`): the authorization decision log and its capture settings.
+- `policyBundles` client resource (`export`, `list`, `current`, `get`, `verify`, `import` with `dry_run` / `prune`) and `verifyPolicyBundle`, which verifies a signed policy bundle offline against your instance JWKS and returns its policies and FGA models.
+- `fga.listUsers` / `fga.listAllUsers` and `openfga.listUsers` / `openfga.listAllUsers`: who has a relation on an object (users, usersets, the `type:*` wildcard with `excluded_users`), paged.
+- `fga.readChanges` and `openfga.readChanges`: the tuple change log, resumable with `continuation_token`.
+- Tuple conditions: `condition` on tuple keys and `context` on `check`, `batchCheck` items, `listObjects` and `listUsers`.
+- `consistency` / `consistency_token` on queries; writes and queries return a `consistency_token`.
+- Desktop login MFA passkeys: `DesktopPasskey` and the policy fields `passkey_scope`, `passkey_rp_id` and `passkey_require_uv`.
+- Connections: `token_family` on connections and `split_tenants` on connect, so one grant covering several accounts (Xero organisations) becomes one connection per account sharing one token set.
+- Custom OAuth providers: `revocation_endpoint`, `host_params_schema` and `data_only` (connect-time host templates for data-only providers).
+- OAuth clients: `claims_redirect_uris` for UMA 2.0 claims gathering.
+- Shared Signals receivers: the `sync_posture` action records device posture without touching sessions.
+- Verifiable credentials: mdoc issuer revocation checks (`revocation_policy`: off, best_effort or required).
+
+## 0.25.0 — 2026-10-26
+
+### Added
+
+- `mfaFactors` client resource for the additional authentication factors: `setYubicoSecret` / `removeYubicoSecret`, `setDuoSecret` / `removeDuoSecret` / `duoHealthCheck`, `setSmartCardSecret` / `removeSmartCardSecret` (all write-only), `yubikeys` (`list`, `register`, `remove`), `smartCardMappings` (`list`, `add`, `remove`) and `resetSecurityQuestions`.
+- `users.create({ mfa })` is typed (`ImportedMfa`): an authenticator (`totp`: SHA-1/256/512, 6 or 8 digits, 30 or 60 seconds) or a counter-based token (`hotp`), plus recovery codes.
 
 ## 0.24.0 — 2026-10-25
 

package/dist/client/abac.d.ts

@@ -0,0 +1,521 @@
+import { type RequestFn } from './request';
+import type { ListPage } from './types';
+import type { Filter, SqlColumn, SqlDialect } from '@atlasauth/authz';
+export interface AbacPolicyTestCase {
+    name: string;
+    /** principal, action, resource, context and optional entities. */
+    request: Record<string, unknown>;
+    expect: 'allow' | 'deny';
+}
+/** An ABAC policy: named, versioned source in the Cedar-subset policy language. */
+export interface AbacPolicy {
+    object: 'abac_policy';
+    id: string;
+    name: string;
+    description: string | null;
+    enabled: boolean;
+    current_version: number;
+    /** The FGA store `fga.check(...)` in the source consults. */
+    fga_store_id: string | null;
+    source: string;
+    tests: AbacPolicyTestCase[];
+    created_at: number;
+    updated_at: number;
+}
+export interface AbacPolicyVersion {
+    object: 'abac_policy_version';
+    policy_id: string;
+    version: number;
+    source: string;
+    tests: AbacPolicyTestCase[];
+    current: boolean;
+    created_at: number;
+}
+export interface CreateAbacPolicyBody {
+    name: string;
+    description?: string | null;
+    enabled?: boolean;
+    fga_store_id?: string | null;
+    source: string;
+    tests?: AbacPolicyTestCase[];
+}
+/** Sending `source` appends a new version; `current_version` (without source) rolls back. */
+export type UpdateAbacPolicyBody = Partial<CreateAbacPolicyBody> & {
+    current_version?: number;
+};
+export interface AbacEntity {
+    type: string;
+    id: string;
+    attributes?: Record<string, unknown>;
+    /** `Type::id` uids this entity is a member of (for `in`). */
+    parents?: string[];
+}
+export interface AbacEvaluateBody {
+    principal: AbacEntity;
+    action: string;
+    resource: AbacEntity;
+    context?: Record<string, unknown>;
+    entities?: AbacEntity[];
+    /** Evaluate only these policies (default: every enabled one). */
+    policy_ids?: string[];
+}
+export interface AbacDecision {
+    object: 'abac_decision';
+    decision: 'allow' | 'deny';
+    reasons: string[];
+    errors: string[];
+}
+export interface AbacCoverageClause {
+    kind: 'when' | 'unless';
+    index: number;
+    line: number | null;
+    true: number;
+    false: number;
+    error: number;
+}
+/** Which rules and `when`/`unless` clauses the test cases exercised. */
+export interface AbacCoverage {
+    object: 'abac_coverage';
+    tests: number;
+    rules: Array<{
+        rule: number;
+        effect: 'permit' | 'forbid';
+        line: number | null;
+        in_scope: number;
+        matched: number;
+        status: 'covered' | 'partial' | 'untouched';
+        clauses: AbacCoverageClause[];
+    }>;
+    summary: {
+        rules: number;
+        reached: number;
+        matched: number;
+        clauses: number;
+        clauses_both_ways: number;
+        percent: number;
+    };
+    /** What to add a test for, one sentence each. */
+    gaps: string[];
+}
+export interface AbacTestRun {
+    object: 'abac_policy_test_run';
+    passed: boolean;
+    results: Array<{
+        name: string;
+        expect: 'allow' | 'deny';
+        actual: 'allow' | 'deny';
+        passed: boolean;
+    }>;
+    coverage: AbacCoverage;
+}
+export interface AbacEntityRef {
+    type: string;
+    id: string;
+}
+/** A policy template: source with `?principal` / `?resource` slots, filled by links. */
+export interface AbacPolicyTemplate {
+    object: 'abac_policy_template';
+    id: string;
+    name: string;
+    description: string | null;
+    source: string;
+    version: number;
+    slots: Array<'?principal' | '?resource'>;
+    fga_store_id: string | null;
+    link_count: number;
+    /** On an update that changed `source`: the links that now evaluate the new source. */
+    links_updated?: number;
+    created_at: number;
+    updated_at: number;
+}
+export interface CreateAbacTemplateBody {
+    name: string;
+    source: string;
+    description?: string | null;
+    fga_store_id?: string | null;
+}
+export interface AbacPolicyLink {
+    object: 'abac_policy_link';
+    id: string;
+    name: string;
+    template_id: string;
+    template_name: string | null;
+    /** The template version the link follows (always the latest). */
+    template_version: number | null;
+    principal: AbacEntityRef | null;
+    resource: AbacEntityRef | null;
+    enabled: boolean;
+    /** The policy source the link evaluates: the template with its slots filled. */
+    source: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface CreateAbacLinkBody {
+    template_id: string;
+    name: string;
+    principal?: AbacEntityRef | null;
+    resource?: AbacEntityRef | null;
+    enabled?: boolean;
+}
+export type AbacSchemaType = {
+    type: 'boolean' | 'long' | 'string';
+} | {
+    type: 'set';
+    element: AbacSchemaType;
+} | {
+    type: 'entity';
+    name: string;
+} | {
+    type: 'record';
+    attributes: Record<string, AbacSchemaType & {
+        required?: boolean;
+    }>;
+};
+/** The entity schema policies are type-checked against when saved. */
+export interface AbacSchemaDocument {
+    entity_types: Record<string, {
+        attributes?: Record<string, AbacSchemaType & {
+            required?: boolean;
+        }>;
+        member_of?: string[];
+    }>;
+    actions?: Record<string, {
+        applies_to?: {
+            principal_types: string[];
+            resource_types: string[];
+            context?: Record<string, AbacSchemaType & {
+                required?: boolean;
+            }>;
+        };
+        member_of?: string[];
+    }>;
+}
+export interface AbacPolicyIssue {
+    severity: 'error' | 'warning';
+    /** 1-based position of the policy in the source (0 for a syntax error). */
+    policy: number;
+    rule: 'permit' | 'forbid';
+    clause?: {
+        kind: 'when' | 'unless';
+        index: number;
+    };
+    message: string;
+    offset?: number;
+    line?: number;
+    column?: number;
+    source_name?: string;
+}
+export interface AbacSchemaState {
+    object: 'abac_schema';
+    schema: AbacSchemaDocument | null;
+    version: number;
+    updated_at: number | null;
+    /** On a save: the errors the schema would give the policies and links already stored. */
+    policy_issues?: AbacPolicyIssue[];
+}
+export interface AbacValidation {
+    object: 'abac_validation';
+    valid: boolean;
+    schema_checked: boolean;
+    issues: AbacPolicyIssue[];
+}
+export interface AbacDiffChange {
+    request: Record<string, unknown>;
+    before: 'allow' | 'deny';
+    after: 'allow' | 'deny';
+    /** Present when a version uses `fga.check`: the assumption the change holds under. */
+    assuming?: {
+        fga_check: boolean;
+    };
+}
+export interface AbacPolicyDiff {
+    object: 'abac_policy_diff';
+    policy_id?: string;
+    from?: number;
+    to?: number;
+    text: {
+        identical: boolean;
+        added: number;
+        removed: number;
+        lines: Array<{
+            type: 'context' | 'add' | 'remove';
+            text: string;
+            before_line?: number;
+            after_line?: number;
+        }>;
+    };
+    /** The requests whose decision changes; null when `semantic` was false. */
+    semantic: {
+        enumerated: number;
+        space: number;
+        exhaustive: boolean;
+        changed: number;
+        newly_allowed: number;
+        newly_denied: number;
+        by_action: Record<string, {
+            newly_allowed: number;
+            newly_denied: number;
+        }>;
+        changes: AbacDiffChange[];
+        truncated: boolean;
+    } | null;
+}
+export interface AbacDiffOptions {
+    from?: number;
+    to?: number;
+    /** false returns only the text diff. */
+    semantic?: boolean;
+    /** Requests to compare; the space is sampled beyond this. Default 5000. */
+    max_requests?: number;
+    /** Changed requests to list. Default 50. */
+    max_changes?: number;
+}
+export interface AuthzenEvaluation {
+    subject?: {
+        type: string;
+        id: string;
+        properties?: Record<string, unknown>;
+    };
+    resource?: {
+        type: string;
+        id: string;
+        properties?: Record<string, unknown>;
+    };
+    action?: {
+        name: string;
+        properties?: Record<string, unknown>;
+    };
+    context?: Record<string, unknown>;
+}
+/** An entity for partial evaluation: an unknown one needs only its `type`. */
+export interface AbacPartialEntity {
+    type: string;
+    id?: string;
+    attributes?: Record<string, unknown>;
+    parents?: string[];
+}
+export interface AbacPartialBody {
+    principal: AbacPartialEntity;
+    action: string;
+    resource: AbacPartialEntity;
+    context?: Record<string, unknown>;
+    entities?: AbacEntity[];
+    policy_ids?: string[];
+    /** Which entity's attributes are unknown. Default `['resource']`. */
+    unknowns?: Array<'principal' | 'resource'>;
+    /** Replace relationship (`fga.check`) conditions with the ids the FGA store returns. Default true. */
+    resolve_relations?: boolean;
+    /** Ask for a ready-made query: parameterised SQL (field-to-column map) and/or a Prisma where object. */
+    output?: {
+        sql?: {
+            columns: Record<string, SqlColumn>;
+            dialect?: SqlDialect;
+            param_offset?: number;
+        };
+        prisma?: {
+            fields: Record<string, string>;
+        };
+    };
+}
+export interface AbacResidual {
+    object: 'abac_residual';
+    /** `allow` / `deny` when the filter is constant, else `conditional`. */
+    decision: 'allow' | 'deny' | 'conditional';
+    /** The condition on the unknown entity under which the request is allowed. */
+    filter: Filter;
+    permit: Filter;
+    forbid: Filter;
+    unknowns: Array<'principal' | 'resource'>;
+    relations_resolved: boolean;
+    sql?: {
+        text: string;
+        params: unknown[];
+    };
+    prisma?: Record<string, unknown>;
+}
+export interface AbacAccessibleBody {
+    principal: AbacPartialEntity;
+    action: string;
+    /** The Atlas resource type key; policies see its PascalCase form. */
+    resource_type: string;
+    context?: Record<string, unknown>;
+    entities?: AbacEntity[];
+    /** Resources to filter instead of the Atlas ones. */
+    candidates?: Array<{
+        id: string;
+        attributes?: Record<string, unknown>;
+        parents?: string[];
+    }>;
+    policy_ids?: string[];
+    limit?: number;
+    starting_after?: string;
+}
+export interface AbacAccessibleList {
+    object: 'list';
+    data: Array<{
+        object: 'abac_resource';
+        type: string;
+        id: string;
+    }>;
+    has_more: boolean;
+    next_cursor: string | null;
+    total: number;
+    evaluated: number;
+    /** `residual` when one filter was applied to every candidate; `per_resource` when each had to be evaluated. */
+    method: 'residual' | 'per_resource';
+}
+/** AuthZEN 1.0 search request: leave the `id` out of the entity you are looking for. */
+export interface AuthzenSearchRequest {
+    subject?: {
+        type: string;
+        id?: string;
+        properties?: Record<string, unknown>;
+    };
+    resource?: {
+        type: string;
+        id?: string;
+        properties?: Record<string, unknown>;
+    };
+    action?: {
+        name: string;
+        properties?: Record<string, unknown>;
+    };
+    context?: Record<string, unknown>;
+    page?: {
+        limit?: number;
+        token?: string;
+    };
+}
+export interface AuthzenSearchPage {
+    /** Empty on the last page. */
+    next_token: string;
+    count: number;
+    total: number;
+}
+/** ABAC policies and the policy decision point (including the AuthZEN endpoints). */
+export declare function abacResource(request: RequestFn): {
+    list(): Promise<ListPage<AbacPolicy>>;
+    get(id: string): Promise<AbacPolicy>;
+    create(body: CreateAbacPolicyBody, idempotencyKey?: string): Promise<AbacPolicy>;
+    update(id: string, body: UpdateAbacPolicyBody): Promise<AbacPolicy>;
+    delete(id: string): Promise<{
+        object: "abac_policy";
+        id: string;
+        deleted: true;
+    }>;
+    versions(id: string): Promise<ListPage<AbacPolicyVersion>>;
+    /** Run a version's tests (default: current), or a draft `source` and `tests`, without saving. */
+    test(id: string, body?: {
+        version?: number;
+        source?: string;
+        tests?: AbacPolicyTestCase[];
+    }): Promise<AbacTestRun>;
+    /** May `principal` perform `action` on `resource`? */
+    evaluate(body: AbacEvaluateBody): Promise<AbacDecision>;
+    /**
+     * Partial evaluation (data filtering): the condition under which the request is allowed when
+     * an entity is unknown, as a filter AST and, on request, parameterised SQL or a Prisma object.
+     */
+    partialEvaluate(body: AbacPartialBody): Promise<AbacResidual>;
+    /** The resources of a type a principal may perform an action on, one page at a time. */
+    accessibleResources(body: AbacAccessibleBody): Promise<AbacAccessibleList>;
+    /** Policy templates: policy source with `?principal` / `?resource` slots that links fill with entities. */
+    templates: {
+        list(): Promise<ListPage<AbacPolicyTemplate>>;
+        get(id: string): Promise<AbacPolicyTemplate>;
+        create(body: CreateAbacTemplateBody, idempotencyKey?: string): Promise<AbacPolicyTemplate>;
+        /** A new `source` reaches every link at once; it is refused if a link could no longer be filled in or would fail the schema. */
+        update(id: string, body: Partial<CreateAbacTemplateBody>): Promise<AbacPolicyTemplate>;
+        /** A template with links is refused unless `force` (which deletes the links too). */
+        delete(id: string, opts?: {
+            force?: boolean;
+        }): Promise<{
+            object: "abac_policy_template";
+            id: string;
+            deleted: true;
+            links_deleted: number;
+        }>;
+    };
+    /** Links: a template with its slots filled by entities. A link is evaluated from the template's current source. */
+    links: {
+        list(query?: {
+            template_id?: string;
+        }): Promise<ListPage<AbacPolicyLink>>;
+        get(id: string): Promise<AbacPolicyLink>;
+        create(body: CreateAbacLinkBody, idempotencyKey?: string): Promise<AbacPolicyLink>;
+        update(id: string, body: Partial<Omit<CreateAbacLinkBody, "template_id">>): Promise<AbacPolicyLink>;
+        delete(id: string): Promise<{
+            object: "abac_policy_link";
+            id: string;
+            deleted: true;
+        }>;
+    };
+    /** The entity schema: once set, policies and templates are type-checked when saved. */
+    schema: {
+        get(): Promise<AbacSchemaState>;
+        /** Saves the schema and reports the errors it would give the policies already stored (`policy_issues`). */
+        set(schema: AbacSchemaDocument): Promise<AbacSchemaState>;
+        delete(): Promise<{
+            object: "abac_schema";
+            deleted: true;
+        }>;
+        /** Type-check draft source against the saved schema (or `schema`) without saving anything. */
+        validate(body: {
+            source: string;
+            schema?: AbacSchemaDocument;
+            template?: boolean;
+        }): Promise<AbacValidation>;
+    };
+    /** Compare two versions of a policy: the text, and the requests whose decision changes. */
+    diff(id: string, opts?: AbacDiffOptions): Promise<AbacPolicyDiff>;
+    /** The same comparison for two sources you send, without saving. */
+    diffSources(body: {
+        before: string;
+        after: string;
+        semantic?: boolean;
+        max_requests?: number;
+        max_changes?: number;
+    }): Promise<AbacPolicyDiff>;
+    /** AuthZEN 1.0 Subject Search: the subjects of a type that may perform the action on the resource. */
+    authzenSearchSubject(body: AuthzenSearchRequest): Promise<{
+        results: Array<{
+            type: string;
+            id: string;
+        }>;
+        page: AuthzenSearchPage;
+    }>;
+    /** AuthZEN 1.0 Resource Search: the resources of a type the subject may perform the action on. */
+    authzenSearchResource(body: AuthzenSearchRequest): Promise<{
+        results: Array<{
+            type: string;
+            id: string;
+        }>;
+        page: AuthzenSearchPage;
+    }>;
+    /** AuthZEN 1.0 Action Search: the actions the subject may perform on the resource. */
+    authzenSearchAction(body: AuthzenSearchRequest): Promise<{
+        results: Array<{
+            name: string;
+        }>;
+        page: AuthzenSearchPage;
+    }>;
+    /** Convenience: the boolean answer to {@link evaluate}. */
+    isAllowed(body: AbacEvaluateBody): Promise<boolean>;
+    /** AuthZEN 1.0 Access Evaluation. */
+    authzenEvaluation(body: AuthzenEvaluation): Promise<{
+        decision: boolean;
+        context?: Record<string, unknown>;
+    }>;
+    /** AuthZEN 1.0 Access Evaluations (batch). */
+    authzenEvaluations(body: AuthzenEvaluation & {
+        evaluations?: AuthzenEvaluation[];
+        options?: {
+            evaluations_semantic?: "execute_all" | "deny_on_first_deny" | "permit_on_first_permit";
+        };
+    }): Promise<{
+        evaluations: Array<{
+            decision: boolean;
+        }>;
+    }>;
+};
+export { FilterCompileError, evalFilter, filterToDrizzle, filterToPrisma, filterToSql, type DrizzleOps, type DrizzleOptions, type Filter, type FilterRows, type PrismaOptions, type SqlColumn, type SqlDialect, type SqlFragment, type SqlOptions, } from '@atlasauth/authz';