@vess-id/ai-identity 0.0.0-dev-20260902121045

package/dist/types/permission-vc.d.ts

@@ -0,0 +1,800 @@
+/**
+ * Permission VC Claims Schema v2
+ *
+ * This is the CANONICAL format for Permission Verifiable Credential claims.
+ * All VC issuance paths MUST produce claims conforming to this schema.
+ * The PolicyEvaluator consumes this schema directly.
+ *
+ * Design principles:
+ * - Grant data is normalized into this format during VC issuance
+ * - PermissionRule is the atomic unit of authorization
+ * - Resource representation uses provider + type + id/pattern (OPA-compatible)
+ * - Constraints are carried per-rule for fine-grained control
+ * - Future OPA integration: this schema maps directly to OPA input document
+ */
+/**
+ * Service provider identifier.
+ * @deprecated Import { CanonicalProvider, AnyProvider } from '@vess-id/ai-identity' registry instead.
+ *             Kept for backward compatibility with existing code.
+ */
+export type Provider = 'slack' | 'github' | 'google' | 'drive' | 'gmail' | 'jira';
+/**
+ * Resource target within a permission rule.
+ *
+ * Separates provider from resource type (unlike Grant's combined "slack:channel").
+ * This enables cleaner OPA policy evaluation and avoids string-parsing at runtime.
+ *
+ * @example
+ * ```typescript
+ * // Specific channel
+ * { type: 'channel', id: 'C123456' }
+ *
+ * // Pattern match
+ * { type: 'channel', pattern: 'public-*' }
+ *
+ * // All resources of a type
+ * { type: 'channel', id: '*' }
+ *
+ * // All resource types for a provider
+ * { type: '*', id: '*' }
+ * ```
+ */
+export interface PermissionResource {
+    /** Resource type (e.g., 'channel', 'repo', 'file', 'issue') */
+    type: string;
+    /** Specific resource ID. Use '*' for all resources of this type. */
+    id?: string;
+    /** Glob pattern for resource ID matching (e.g., 'public-*', 'team-?-dev') */
+    pattern?: string;
+    /** Tenant reference (e.g., workspace ID, org ID) */
+    tenant_ref?: string;
+}
+/**
+ * Time window constraint.
+ *
+ * Supports both:
+ * - Recurring windows (start/end HH:mm with daysOfWeek) - from Grant model
+ * - Absolute windows (not_before/not_after unix timestamps) - for VC-level
+ *
+ * The VC issuance layer converts Grant's recurring windows into the
+ * appropriate format based on context.
+ */
+export interface PermissionTimeConstraint {
+    /** Absolute not-before (unix timestamp) */
+    not_before?: number;
+    /** Absolute not-after (unix timestamp) */
+    not_after?: number;
+    /** Recurring: allowed time start (HH:mm, UTC unless timezone specified) */
+    recurring_start?: string;
+    /** Recurring: allowed time end (HH:mm, UTC unless timezone specified) */
+    recurring_end?: string;
+    /** Recurring: allowed days of week (0=Sun, 1=Mon...6=Sat) */
+    days_of_week?: number[];
+    /** Timezone for recurring constraints (default: 'UTC') */
+    timezone?: string;
+}
+/**
+ * Rule-level constraints embedded in each PermissionRule.
+ *
+ * These are evaluated at policy decision time and support both
+ * Grant-originated constraints and VC-specific constraints.
+ */
+export interface PermissionConstraints {
+    /** Time constraints */
+    time?: PermissionTimeConstraint;
+    /** Maximum invocations for this specific rule */
+    max_invocations?: number;
+    /** Rate limiting (requests per minute) */
+    rate_limit_per_min?: number;
+    /** Allowed IP ranges (CIDR notation) */
+    ip_allowlist?: string[];
+    /** Maximum risk score threshold (0-100) */
+    risk_threshold?: number;
+    /** Purpose description (for audit trail) */
+    purpose?: string;
+    /** Scope constraints (provider-specific, e.g., { thread_id: 'T123' }) */
+    scope?: Record<string, unknown>;
+    /**
+     * Target constraints for secondary destinations (cc, attendees, etc.).
+     * Alpha: defined but NOT evaluated by ConstraintEvaluator.
+     * Future: evaluated against PolicyInput.request.targets.
+     */
+    targets?: import('./target-binding').TargetConstraint[];
+}
+/**
+ * Inline policy mode — full Cedar policy embedded in the VC.
+ *
+ * Used for sub-agent re-delegation where the verifier cannot reach the
+ * Policy Registry over the network. The inline policy is authoritative;
+ * `policy_hash` is a sanity check for tamper-evidence.
+ *
+ * Spec refs:
+ * - docs/specs/2026-05-23-cedar-rar-permission-redesign.md §3.2
+ */
+export interface PolicyRefInline {
+    mode: 'inline';
+    /** Full Cedar policy source (PolicySet text, UTF-8). */
+    policy_inline: string;
+    /** sha256 of `policy_inline` (hex), prefixed `sha256-` for tamper-evidence. */
+    policy_hash: string;
+    /**
+     * Cedar schema fragment id. **Phase 1 unused** (Cedar wasm schema-less
+     * evaluation, Implementation plan §1.1). **Phase 2+ で per-policy schema
+     * 切替時に inline モードでは REQUIRED 化** (reference モードは Registry
+     * resolve で取得できるため optional のまま).
+     */
+    schema_id?: string;
+    /**
+     * Policy engine that authored / evaluates this document. Omitted ⇒ `cedar`
+     * (historical default — all pre-Plan-B refs are Cedar and MUST stay wire-
+     * identical). Corresponds to the Policy Registry `engine` column (Plan B
+     * Task 1). Non-cedar engines (e.g. `'scheduling-delegation/v1'`) carry a
+     * non-Cedar `policy_inline` body and skip Cedar lint.
+     */
+    engine?: string;
+}
+/**
+ * Reference policy mode — policy lives in the Policy Registry.
+ *
+ * The verifier fetches `policy_uri` (must match the issuer's
+ * `/.well-known/policy-registry/:policy_id`), validates `policy_hash`,
+ * and evaluates the fetched Cedar policy.
+ *
+ * Spec refs:
+ * - docs/specs/2026-05-23-cedar-rar-permission-redesign.md §3.2
+ */
+export interface PolicyRefReference {
+    mode: 'reference';
+    /** Policy Registry id. Format: `pol_<project_id>_<uuidv7>`. */
+    policy_id: string;
+    /** Absolute URL to `/.well-known/policy-registry/:policy_id`. */
+    policy_uri: string;
+    /** sha256 of the served Cedar policy text (hex), prefixed `sha256-`. */
+    policy_hash: string;
+    /**
+     * Cedar schema fragment id. Phase 1 unused (Registry resolve で取得可能、
+     * schema-less evaluation を使う簡易構成)。Phase 2+ で per-policy schema を
+     * 導入したときも reference モードは引き続き OPTIONAL — VC payload に
+     * 同梱せず Registry 側で resolve する方針。
+     */
+    schema_id?: string;
+    /**
+     * Policy engine that authored / evaluates the referenced document. Omitted ⇒
+     * `cedar` (historical default — all pre-Plan-B refs are Cedar and MUST stay
+     * wire-identical). Corresponds to the Policy Registry `engine` column (Plan B
+     * Task 1); the served `/.well-known/policy-registry/:id` document declares the
+     * same value. Non-cedar engines (e.g. `'scheduling-delegation/v1'`) resolve to
+     * a non-Cedar body and skip Cedar lint.
+     */
+    engine?: string;
+}
+/**
+ * Tagged union of policy reference shapes. Discriminator: `mode`.
+ *
+ * Use {@link isPolicyRefInline} / {@link isPolicyRefReference} for runtime
+ * narrowing.
+ */
+export type PolicyRef = PolicyRefInline | PolicyRefReference;
+/** Type guard for {@link PolicyRefInline}. */
+export declare function isPolicyRefInline(ref: PolicyRef): ref is PolicyRefInline;
+/** Type guard for {@link PolicyRefReference}. */
+export declare function isPolicyRefReference(ref: PolicyRef): ref is PolicyRefReference;
+/**
+ * Permission Rule - the atomic unit of authorization.
+ *
+ * Each rule grants specific actions on specific resources for a specific provider.
+ * Rules are evaluated independently during policy evaluation.
+ *
+ * Phase 1 (Cedar + RAR redesign) extensions:
+ * - `effect` widened from `'allow'` only to the 3-valued
+ *   `'allow' | 'deny' | 'require_approval'` (spec §5).
+ *   Existing call-sites that only used `'allow'` remain source-compatible.
+ * - `priority` field added (optional, used for deterministic ordering when
+ *   multiple rules match the same request).
+ * - `policy_ref` field added (optional in Phase 1 for backward-compat
+ *   during migration; Phase 2+ will bump the schema to v3.1 and make it
+ *   required — see spec §3.1 reconciliation note).
+ *
+ * OPA mapping (legacy `'allow'`-only path, still used while
+ * `CEDAR_POLICY_ENABLED != enforce`):
+ * ```rego
+ * allow {
+ *   some rule in input.credentials.delegates
+ *   rule.effect == "allow"
+ *   rule.provider == input.request.provider
+ *   glob.match(rule.resource.type, [], input.request.resource.type)
+ *   resource_id_matches(rule.resource, input.request.resource.id)
+ *   action_matches(rule.actions, input.request.action)
+ *   constraints_satisfied(rule.constraints, input.environment)
+ * }
+ * ```
+ */
+export interface PermissionRule {
+    /** Rule identifier (for audit trail and matched_rule_id) */
+    id?: string;
+    /**
+     * Effect. Phase 1 widens this beyond legacy `'allow'`-only:
+     * - `'allow'`            — permit the action (legacy default).
+     * - `'deny'`             — explicit deny (override precedence over allow).
+     * - `'require_approval'` — pause and request human approval.
+     */
+    effect: 'allow' | 'deny' | 'require_approval';
+    /**
+     * Optional priority for deterministic ordering when multiple rules match.
+     * Higher priority wins. Phase 1 evaluator behaviour is unchanged when
+     * `priority` is absent.
+     */
+    priority?: number;
+    /** Service provider */
+    provider: Provider | string;
+    /** Target resource */
+    resource: PermissionResource;
+    /** Allowed actions (e.g., ['post_message', 'read_history']). '*' for all. */
+    actions: string[];
+    /** Rule-level constraints */
+    constraints?: PermissionConstraints;
+    /**
+     * RAR authorization-details type (RFC 9396 §2), carried verbatim (#952).
+     *
+     * A free-form URN naming the kind of authorization this delegate represents,
+     * for consumers that speak RAR. Deliberately unvalidated: the registry of
+     * types belongs to whoever issues them, and rejecting an unrecognised URN
+     * here would make this service the gatekeeper of a vocabulary it does not
+     * own.
+     *
+     * NOT an authorization input. Gate-2 authorises on `provider`, `actions`,
+     * `resource.type` and `resource.id`; a credential must not be able to widen
+     * or narrow what it may do by naming a type. Note how close this sits to
+     * `resource.type`, which Gate-2 *does* read — the two are one level apart
+     * and the format is unchecked, so a line reaching for the wrong one would
+     * not be caught by the compiler or at runtime. Pinned in
+     * `gate2-fast-path.spec.ts` ("delegates[].type is inert at Gate-2").
+     */
+    type?: string;
+    /**
+     * Cedar policy binding (Phase 1).
+     *
+     * When present, the policy engine evaluates this delegate via the
+     * referenced / inlined Cedar policy in addition to the static constraint
+     * check. Optional in Phase 1 for backward-compat during migration; Phase
+     * 2+ will bump the schema to v3.1 and make it required.
+     */
+    policy_ref?: PolicyRef;
+    /**
+     * Cedar policy bindings (複数) — 1 つの委任スコープに複数の policy が AND/OR
+     * で適用されるケース (例: calendarDomain 宛先制約 + timeWindow forbid)。
+     * 後方互換のため単数 `policy_ref` は維持し、発行時は `policy_refs[0]` を
+     * ミラーする。読み手は policy_refs を優先し、無ければ policy_ref を単要素配列に
+     * 正規化する。Cedar 評価では全 ref を 1 つの PolicySet に集約 (permit=OR,
+     * forbid=override で AND)。
+     */
+    policy_refs?: PolicyRef[];
+}
+/**
+ * Permission VC Claims v2 — the pre-Cedar canonical credential claims format.
+ *
+ * This is what gets signed into the SD-JWT VC. All VC issuance paths
+ * (VCService, RemoteVCIssuerService, PermissionVCManager) MUST produce
+ * claims conforming to either this interface or {@link PermissionVcClaims_V3}.
+ *
+ * The Grant → VC normalization layer converts:
+ * - GrantResource[] + actions[] → PermissionRule[]
+ * - GrantConstraints → PermissionConstraints (per-rule)
+ * - Grant metadata → top-level claims fields
+ *
+ * @remarks Phase 1 Step 2 renamed the original `PermissionVcClaims` to
+ * `PermissionVcClaims_V2`. The exported alias {@link PermissionVcClaims}
+ * is now a union of V2 + {@link PermissionVcClaims_V3}, preserving
+ * existing import sites (they will accept both shapes).
+ */
+export interface PermissionVcClaims_V2 {
+    /** Schema version */
+    v: '2';
+    /** Credential type discriminator */
+    type: 'PermissionCredential';
+    /** Issuer DID (user who granted permission) */
+    iss: string;
+    /** Subject DID (agent receiving permission) */
+    sub: string;
+    /** Issued at (unix timestamp) */
+    iat: number;
+    /** Not before (unix timestamp) */
+    nbf?: number;
+    /** Expiration (unix timestamp) */
+    exp: number;
+    /** JWT ID (unique credential identifier) */
+    jti: string;
+    /** Project ID */
+    project_id: string;
+    /** User ID (grant owner) */
+    user_id?: string;
+    /** User DID (grant owner) */
+    user_did?: string;
+    /** Source grant IDs (supports multiple grants aggregated into one VC) */
+    grant_ids: string[];
+    /**
+     * Primary grant ID (derived from grant_ids[0]).
+     * @deprecated Use grant_ids instead. Kept for backward-compat JWT claims.
+     *   Always set via {@link buildGrantIdFields} to keep both fields in sync.
+     */
+    grant_id: string;
+    /** Session ID (binds VC to specific session) */
+    session_id: string;
+    /** Parent JWT ID for re-delegation chain (not supported in MVP) */
+    parent_jti?: string;
+    /** Confirmation (Proof of Possession binding) */
+    cnf?: {
+        /** JWK for Proof of Possession (SD-JWT KB-JWT standard) */
+        jwk: Record<string, unknown>;
+    };
+    /** Delegated permission rules (the core authorization data) */
+    delegates: PermissionRule[];
+}
+/**
+ * Permission VC Claims v3 — Cedar + RAR Phase 1 schema.
+ *
+ * Inherits all V2 fields and adds two Phase-1-aware extensions:
+ * - `cedar_schema_ref?` — pointer to the Cedar schema fragment the
+ *   delegates were authored against. **Phase 1 unused** (the SDK ships a
+ *   single global schema fragment generated by connector-plugin codegen,
+ *   per Implementation plan §1.1). Reserved for Phase 2+ per-policy schema
+ *   switching.
+ * - `layer?` — chain hierarchy layer. **Phase 2+ only**; Phase 1 issuance
+ *   pins this to `'agent_permission'` via {@link buildPhase1VcClaims}.
+ *   Direct assignment is discouraged (ESLint rule planned in Step 5).
+ *
+ * Spec refs:
+ * - docs/specs/2026-05-23-cedar-rar-permission-redesign.md §3.1
+ * - docs/specs/2026-05-23-cedar-rar-implementation-plan-phase1.md Task 2.1 / 2.5
+ */
+/**
+ * Bug B 真因修正 (β, 2026-05-28) — VC=mandate semantic を invoke 時 Cedar も
+ * 信じるため、approval の事実 (誰がいつ何を approve したか) を VC に焼き込む
+ * signed self-attestation。SD-protected (`_sd` 経由 disclosure)、SD-JWT 署名で
+ * 改竄不可。invoke 時 Cedar context.approval の最優先 source として採用。
+ *
+ * Forward compat: A2A AP2 Mandate (IntentMandate / CartMandate / PaymentMandate)
+ * との projection は Phase 2 spec で別途定義。本 field 名は内部
+ * ApprovalContext (snake_case) と一貫。
+ *
+ * Spec ref: docs/superpowers/plans/2026-05-28-bug-b-fix-beta-vc-embed-approval.md
+ */
+export interface VcApprovalClaim {
+    /** `req_<uuid>` — 元 approval-request id (claimVC 元 request の id)。 */
+    request_id: string;
+    /** `outcome_<uuid>` — APPROVAL_OUTCOME audit event id (§11.1 join key)。 */
+    outcome_id: string;
+    /** approver の user id、または 'system' (auto-approve 経路)。最大 128 chars。 */
+    granted_by: string;
+    /** ISO-8601 timestamp of the approval action. */
+    granted_at: string;
+    /**
+     * #884 Task 5 (INV-4) — the concrete CANONICAL resource id the approval
+     * applied to (e.g. `'octocat/repo'`, `'C0123ABC'`). NAMES the tuple the
+     * approver actually consented to so the issued VC records WHAT was approved,
+     * not merely THAT something was. Optional for backward compatibility:
+     * absent for base-path / legacy approvals that selected no concrete resource.
+     */
+    resource_id?: string;
+    /**
+     * #884 Task 5 — the action the approval applied to (e.g.
+     * `'github.issue.update'`). Pairs with {@link resource_id} to fully name the
+     * approved (action, resource) tuple. Optional for backward compatibility.
+     */
+    action?: string;
+    /**
+     * #1205 P1 (decision-bound authorization) — `sha256:` hex of the
+     * canonicalized approved salient params. Binds the issued VC to the CONCRETE
+     * parameter values the approver consented to, so a caller cannot execute with
+     * different (e.g. tampered `body`/`to`) parameters under the same approval.
+     * Computed at claimVC (Step 4) from the final persisted `actionParams`;
+     * verified fail-closed at the PEP (Step 5). Absent on legacy VCs and on
+     * actions that declare no salient set.
+     */
+    params_hash?: string;
+}
+/**
+ * Scheduling Wow Phase 1 §5.3 (Task 7) — the delegation-policy snapshot baked
+ * into a VC that was AUTO-ISSUED (no human approval) because the invocation
+ * fell entirely inside the user's advance scheduling-delegation policy.
+ *
+ * Audit evidence: names WHAT standing authority the auto-issuance relied on
+ * ("何を根拠に自動実行されたか"), so a verifier / auditor can reconstruct the
+ * decision without the DB row (which may have been edited since). It is NOT
+ * read by any enforcement gate — resource_id / delegates semantics (#884
+ * canonical resource checks) are unchanged.
+ *
+ * SD-protected (disclosed via `_sd`) because `contactScope` can contain
+ * third-party emails/domains.
+ *
+ * Item binding (Tasks 9-11, spec §5.3): the optional {@link
+ * VcSchedulingDelegationClaim.itemId} names which negotiation an automated
+ * calendar write belonged to. It is ABSENT on `scheduling.request` issuances
+ * (at that gate the item does not exist yet — it is created by the request
+ * pipeline AFTER the VC gate, so there is nothing to bind) and PRESENT on the
+ * confirm (§7) and tentative-hold (§6) issuance contexts, which operate on a
+ * concrete item.
+ */
+export interface VcSchedulingDelegationClaim {
+    /** The policy's allowed weekly window at issuance time. */
+    timeWindow: {
+        /** Allowed weekdays, 0 (Sun) – 6 (Sat). */
+        daysOfWeek: number[];
+        /** 'HH:mm' wall-clock window start (policy timezone). */
+        windowStart: string;
+        /** 'HH:mm' wall-clock window end (policy timezone). */
+        windowEnd: string;
+        /** IANA timezone the window is judged in (e.g. 'Asia/Tokyo'). */
+        timezone: string;
+    };
+    /** Upper bound on meeting duration (minutes) the policy allowed. */
+    maxDurationMinutes: number;
+    /** Counterpart scope the policy allowed. null = no restriction. */
+    contactScope: {
+        emails: string[];
+        domains: string[];
+    } | null;
+    /** ISO-8601 expiry of the delegation policy itself at issuance time. */
+    policyExpiresAt: string;
+    /**
+     * Scheduling Wow Phase 1 (Tasks 9-11, spec §5.3) — the inbox item id the
+     * automated calendar write belonged to. ADDITIVE / OPTIONAL: absent on
+     * `scheduling.request` issuances (the item does not exist yet at that gate),
+     * present on the confirm (§7) and tentative-hold (§6) issuance contexts,
+     * which DO operate on a concrete item and bind it so the audit evidence names
+     * which negotiation the write was for.
+     */
+    itemId?: string;
+    /**
+     * Scheduling Phase 2 §A / Plan A' (Task A6, spec §7 / §8.3) — the id of the
+     * standing booking link this automated calendar write was booked THROUGH. Present
+     * on the pull-type booking confirm path (a visitor 1-clicks a slot from an
+     * owner's booking link); ADDITIVE / OPTIONAL — absent on the push-type
+     * `scheduling.request` / confirm (§7) / hold (§6) contexts, which have no link.
+     *
+     * AUDIT-ONLY, same principle as the rest of this claim: no enforcement gate
+     * reads it. The audit evidence names which booking link the write belonged to
+     * so an auditor can reconstruct the standing pull-type authority; invoke-time
+     * authorization is unaffected (#884 unchanged).
+     */
+    linkId?: string;
+    /**
+     * Scheduling Phase 2 Plan B (Task 3 bakes this) — the Policy Registry id of
+     * the signed delegation-policy document the auto-issuance relied on. Lets an
+     * auditor fetch the exact JWS-signed `/.well-known/policy-registry/:id`
+     * document that this snapshot was derived from, instead of trusting the
+     * inline snapshot alone. ADDITIVE / OPTIONAL: absent on legacy rows minted
+     * before Plan B (which have no registry document).
+     *
+     * AUDIT-ONLY, same principle as the rest of this claim: no enforcement gate
+     * reads it. At invoke time the delegation is re-evaluated against the LIVE
+     * policy row + actual request parameters — the VC claim is never trusted as
+     * an authorization source (#884 canonical resource checks unchanged).
+     */
+    policyRegistryId?: string;
+    /**
+     * Scheduling Phase 2 Plan B (Task 3 bakes this) — `sha256-` prefixed hash of
+     * the canonical policy body the {@link policyRegistryId} document was minted
+     * with. Tamper-evidence linking this snapshot to that exact document version.
+     * ADDITIVE / OPTIONAL: absent on legacy rows minted before Plan B.
+     *
+     * AUDIT-ONLY, same principle as the rest of this claim: no enforcement gate
+     * reads it. Invoke-time evaluation trusts the live policy row + actual
+     * parameters, never the VC claim (#884 unchanged).
+     */
+    policyHash?: string;
+}
+export interface PermissionVcClaims_V3 extends Omit<PermissionVcClaims_V2, 'v'> {
+    /** Schema version — v3 adds Cedar policy_ref support and chain hierarchy fields. */
+    v: '3';
+    /**
+     * Cedar schema fragment reference (Phase 2+ per-policy schema switching).
+     * Phase 1: unused; SDK uses connector-plugin codegen global schema.
+     */
+    cedar_schema_ref?: {
+        /** e.g. `cedar_schema_2026_05_23_v1`. */
+        schema_id: string;
+        /** sha256 of the schema fragment (hex). */
+        schema_hash: string;
+    };
+    /**
+     * 4-layer chain (Org Policy → User Grant → Agent Permission → Sub-Agent Delegation).
+     * Phase 1 では `buildPhase1VcClaims()` factory 経由で `'agent_permission'` が固定セットされる。
+     * Phase 2+ では本フィールドを **required** に格上げする予定 (V3.1 schema)。
+     * 直接代入は禁止 (Phase 1 では factory を使うこと、Phase 2+ では ESLint rule で強制)。
+     * 詳細: design spec §3.1, §6.1 / Phase 1 plan Task 2.5。
+     */
+    layer?: 'org_policy' | 'user_grant' | 'agent_permission' | 'sub_agent_delegation';
+    /**
+     * Bug B 真因修正 (β, 2026-05-28) — approval メタを VC に焼き込む。
+     * VC=mandate なので「この VC が発行されたこと自体が approve の証拠」だが、
+     * invoke 時 Cedar に `context.approval.granted == true` を渡せるよう
+     * back-ref を明示。本 field 不在 = base path (legacy 互換、Cedar は token-
+     * ledger 経由 fallback)。{@link VcApprovalClaim} 参照。
+     */
+    approval?: VcApprovalClaim;
+    /**
+     * Scheduling Wow Phase 1 §5.3 (Task 7) — present ONLY when the VC was
+     * auto-issued under the user's advance scheduling-delegation policy
+     * (scheduling.request / confirm / hold contexts). Absent on every other
+     * issuance path (manual approval, Cedar permit, legacy). Audit-only:
+     * no enforcement gate reads it. {@link VcSchedulingDelegationClaim}.
+     */
+    schedulingDelegation?: VcSchedulingDelegationClaim;
+    /**
+     * How this credential came to exist (#954).
+     *
+     * - `'user_approved'` — a person consented. Paired with {@link approval},
+     *   which carries the back-reference to the approval request and outcome.
+     * - `'auto_issued'` — consent was given on the user's behalf: a Cedar
+     *   permit, an advance delegation policy, or a signup funnel.
+     * - `'unrecorded'` — provenance is genuinely unknown. Credentials issued
+     *   before the consent type was recorded, and any path where no approval
+     *   assertion reaches the issuer, land here.
+     *
+     * Derived from the approval's `consent_type` — HOW the consent was
+     * obtained — and never from `granted_by`, which records WHO. Those come
+     * apart in practice: booking start writes `granted_by: 'system'` for both
+     * an explicit human click and an automatic funnel, because the visitor's
+     * identity is gone by the time the credential is issued.
+     *
+     * The third value is not a placeholder to be tidied away later. Guessing
+     * between the other two would fabricate audit data, and this claim is
+     * signed — it cannot be corrected once issued.
+     *
+     * Never taken from the request: `approvalAssertion` is an internal-only
+     * extension on `issueVC` precisely so this stays true (see the comment on
+     * `IssueVCRequestDto`).
+     *
+     * Optional, and permanently so. The type describes credentials that are
+     * already signed and in circulation; those cannot be re-issued to carry a
+     * new field, so a required one would invalidate them at the type layer.
+     * Absent means "issued before #954", not "auto-issued".
+     *
+     * Audit and disclosure metadata — no gate reads it to decide anything. If a
+     * gate ever should, the decision belongs in policy, against `approval`,
+     * rather than against a label the issuer wrote about itself.
+     */
+    issuance_mode?: 'user_approved' | 'auto_issued' | 'unrecorded';
+    /**
+     * Why this credential was requested, in the requester's own words (#955).
+     *
+     * Free text, deliberately. Narrowing it to a vocabulary would turn a
+     * description into a decision input, and Phase 1 neither records nor
+     * evaluates it (DEV-INSTRUCTIONS §256) — no gate reads it, and none should
+     * without that being a decision someone makes on purpose.
+     *
+     * SD-protected at issuance. Natural language written by a person tends to
+     * name people, accounts and circumstances, so a verifier gets it only when
+     * the holder chooses to disclose it. Keep it out of audit logs and error
+     * messages for the same reason.
+     *
+     * Optional, and permanently so: the type describes credentials already
+     * signed and in circulation, which cannot be re-issued to carry a new
+     * field.
+     */
+    intent_description?: string;
+}
+/**
+ * Permission VC Claims (canonical union of v2 + v3).
+ *
+ * All existing import sites referencing `PermissionVcClaims` continue to
+ * compile because:
+ * - Code that only produced V2 still produces a value assignable to the
+ *   union.
+ * - Code that consumes the union can narrow on `claims.v === '3'` to
+ *   access V3-only fields.
+ */
+export type PermissionVcClaims = PermissionVcClaims_V2 | PermissionVcClaims_V3;
+/**
+ * Build synchronized grant_id / grant_ids fields for PermissionVcClaims.
+ * Guarantees grant_id === grant_ids[0].
+ */
+export declare function buildGrantIdFields(grantIds: string[]): {
+    grant_ids: string[];
+    grant_id: string;
+};
+/**
+ * Policy evaluation input document.
+ *
+ * Designed to map 1:1 to OPA input document for future integration:
+ * ```rego
+ * package aidentity.authz
+ *
+ * default allow = false
+ *
+ * allow {
+ *   some rule in input.credentials.delegates
+ *   rule_matches(rule, input.request)
+ *   constraints_ok(rule.constraints, input.environment)
+ * }
+ * ```
+ */
+export interface PolicyInput {
+    /** Subject (who is requesting) */
+    subject: {
+        /** Agent DID */
+        agent_did: string;
+        /** Session ID */
+        session_id: string;
+        /** User DID (delegator) */
+        user_did?: string;
+    };
+    /** Tenant context */
+    tenant: {
+        /** Project ID */
+        project_id: string;
+    };
+    /** Request details (what is being requested) */
+    request: {
+        /** Service provider */
+        provider: string;
+        /** Action to perform */
+        action: string;
+        /** Target resource */
+        resource: {
+            type: string;
+            id: string;
+            /** Tenant/workspace reference for multi-account disambiguation (future) */
+            tenant_ref?: string;
+        };
+        /** Secondary targets extracted from tool parameters via TargetResolver */
+        targets?: import('./target-binding').PolicyTarget[];
+        /** Raw tool parameters (for OPA custom policies) */
+        params?: Record<string, unknown>;
+    };
+    /** Credential information (from VC) */
+    credentials: {
+        /** JWT ID */
+        jti: string;
+        /** Source grant IDs */
+        grant_ids: string[];
+        /** Primary grant ID */
+        grant_id: string;
+        /** Issued at timestamp */
+        issued_at: number;
+        /** Expiration timestamp */
+        expires_at: number;
+        /** Delegated permission rules from VC */
+        delegates: PermissionRule[];
+    };
+    /** Environment context (evaluated at request time) */
+    environment: {
+        /** Current timestamp (unix) */
+        now: number;
+        /** Client IP address */
+        ip_address?: string;
+        /** Risk score (0-100) */
+        risk_score?: number;
+        /** Current invocation count for the grant */
+        invocation_count?: number;
+    };
+}
+/**
+ * Policy evaluation result
+ */
+export interface PolicyEvaluationResult {
+    /** Whether the action is allowed */
+    allowed: boolean;
+    /** Denial reason if not allowed */
+    reason?: string;
+    /** Error code for programmatic handling */
+    reason_code?: string;
+    /** Matched rule ID (if allowed) */
+    matched_rule_id?: string;
+    /** Which evaluation step failed (for debugging) */
+    step_failed?: string;
+}
+/**
+ * External Action Request - normalized format for tool invocations.
+ * Used as the bridge between MCP tool calls and policy evaluation.
+ */
+export interface ExternalActionRequest {
+    /** Request ID for idempotency */
+    request_id: string;
+    /** Service provider */
+    provider: Provider | string;
+    /** Action to perform */
+    action: string;
+    /** Target resource */
+    resource: {
+        type: string;
+        id: string;
+    };
+    /** Project ID */
+    project_id: string;
+    /** Session ID */
+    session_id: string;
+    /** Action parameters (sanitized) */
+    params?: Record<string, unknown>;
+}
+/**
+ * Parsed provider and resource type from a Grant's combined resource type string.
+ *
+ * Grant uses "slack:channel" format, but VC uses separate provider + resource.type.
+ * This interface represents the parsed result.
+ */
+export interface ParsedResourceType {
+    provider: string;
+    resourceType: string;
+}
+/**
+ * Parse a Grant resource type string into provider and resource type.
+ *
+ * @example
+ * parseGrantResourceType('slack:channel') // { provider: 'slack', resourceType: 'channel' }
+ * parseGrantResourceType('github:repo')   // { provider: 'github', resourceType: 'repo' }
+ * parseGrantResourceType('slack')         // { provider: 'slack', resourceType: '*' }
+ * parseGrantResourceType('*')            // { provider: '*', resourceType: '*' }
+ */
+export declare function parseGrantResourceType(grantType: string): ParsedResourceType;
+/**
+ * Parse a Grant action string into provider and action.
+ *
+ * Grant actions use "provider.resource.operation" (dot format, canonical) or
+ * legacy "provider:resource.operation" (colon format).
+ * This extracts the provider prefix and the action name.
+ *
+ * @example
+ * parseGrantAction('slack.message.read')         // { provider: 'slack', action: 'message.read' }
+ * parseGrantAction('slack:channel.post_message')  // { provider: 'slack', action: 'channel.post_message' }
+ * parseGrantAction('*')                          // { provider: '*', action: '*' }
+ */
+export declare function parseGrantAction(grantAction: string): {
+    provider: string;
+    action: string;
+};
+/**
+ * The single layer value Phase 1 VC issuance is allowed to emit.
+ *
+ * companion design spec §3.1 defines a 4-layer enum
+ * (`'org_policy' | 'user_grant' | 'agent_permission' | 'sub_agent_delegation'`),
+ * but Phase 1 only issues at the `agent_permission` layer. The other 3
+ * layers unlock in Phase 2+.
+ *
+ * Spec refs:
+ * - docs/specs/2026-05-23-cedar-rar-implementation-plan-phase1.md Task 2.5 (rev 5)
+ * - docs/specs/2026-05-23-cedar-rar-permission-redesign.md §3.1 Phase 1 layer 固定 note
+ */
+export declare const PHASE_1_VC_LAYER: "agent_permission";
+/** Literal type of {@link PHASE_1_VC_LAYER}. */
+export type Phase1VcLayer = typeof PHASE_1_VC_LAYER;
+/**
+ * Build a {@link PermissionVcClaims_V3} object with `layer` pinned to
+ * {@link PHASE_1_VC_LAYER} (`'agent_permission'`).
+ *
+ * **This factory is mandatory for Phase 1 VC issuance.** Direct assignment
+ * of `layer` on a V3 claims literal is discouraged and will be guarded by
+ * an ESLint rule once Step 5 wires usage in
+ * `packages/api/src/grant/services/remote-vc-issuer.service.ts`. Phase 2+
+ * will relax or delete this factory when the other 3 layers unlock.
+ *
+ * The input `base` type explicitly omits `layer` so passing it is a
+ * compile-time error — guaranteeing call-sites cannot accidentally
+ * smuggle a non-Phase-1 layer value through.
+ *
+ * @example
+ * ```ts
+ * import { buildPhase1VcClaims } from '@vess-id/ai-identity'
+ *
+ * const claims = buildPhase1VcClaims({
+ *   v: '3',
+ *   type: 'PermissionCredential',
+ *   iss: userDid,
+ *   sub: agentDid,
+ *   iat: now,
+ *   exp: now + 3600,
+ *   jti,
+ *   project_id,
+ *   grant_ids,
+ *   grant_id,
+ *   session_id,
+ *   delegates,
+ * })
+ * // claims.layer is type-narrowed to 'agent_permission'
+ * ```
+ */
+export declare function buildPhase1VcClaims(base: Omit<PermissionVcClaims_V3, 'layer'>): PermissionVcClaims_V3 & {
+    layer: Phase1VcLayer;
+};
+//# sourceMappingURL=permission-vc.d.ts.map