@hasna/skills 0.10.43 → 0.10.44

package/dist/lib/agent-integration.d.ts

@@ -1,5 +1,6 @@
 import { type CodexCorpusWriteOptions } from "./codex-corpus-write.js";
 import { type ReviewedCodexSkillDenial } from "./codex-plugin-skill-controls.js";
+import { type CodexNativeHookEnvelope, type ProcessInspector, type NativePolicyHelperRunner } from "./codex-native-skill-policy.js";
 import { type CodexNativeSkillCatalog } from "./codex-native-skill-catalog.js";
 import { type AgentDiscoveryBinding, type ReviewedDiscoveryInputs } from "./agent-discovery.js";
 import { type IntegrationAgent } from "./agent-adapters.js";
@@ -222,16 +223,31 @@ export declare function archiveNativeSkills(inventory: NativeSkillEntry[], optio
         targetCount: number;
     };
 };
-/** Run before any prompt context load. Missing ownership or reappearing native
- * discovery files require repair; verified cache availability is not an override. */
-export declare function assertManagedAgentBridge(agent: IntegrationAgent, options?: {
+/** Native hook input for the Codex policy adapter. Only the Codex hook paths that
+ * receive native SessionStart/UserPromptSubmit input supply it; install-time and
+ * other guard calls never do. `inspector` is a test seam for process lineage. */
+export interface CodexNativePolicyGuardInput extends CodexNativeHookEnvelope {
+    inspector?: ProcessInspector;
+    helperRunner?: NativePolicyHelperRunner; /** Absolute epoch ms by which the hook must answer; bounds the hash and helper. */
+    deadlineMs?: number;
+}
+interface ManagedBridgeOptions {
     home?: string;
     dataDir?: string;
     projectDir?: string;
     projectDirs?: string[];
     profileId?: string;
     codexDiscoveryRecovery?: CodexHookDiscoveryRecovery;
-}): void;
+    codexNativePolicy?: CodexNativePolicyGuardInput;
+}
+/** Package-classified installed-plugin content below the Codex plugin cache that
+ * a verified restricted policy cannot load. Classification is the existing plugin
+ * manifest identity and real-path binding, never a path prefix; user, repo and
+ * project copies, unclassified cache files and any allowed host path refuse. */
+export declare function isInertCodexPluginCacheCopy(entry: NativeSkillEntry, cache: string, allowedHostPaths: readonly string[], read: (path: string) => string): boolean;
+/** Run before any prompt context load. Missing ownership or reappearing native
+ * discovery files require repair; verified cache availability is not an override. */
+export declare function assertManagedAgentBridge(agent: IntegrationAgent, options?: ManagedBridgeOptions): void;
 export declare function normalizeAgentHookPrompt(agent: IntegrationAgent, event: string, prompt: string): string;
 export declare function hookContextOutput(event: string, result: {
     context: string;

package/dist/lib/codex-native-skill-policy.d.ts

@@ -0,0 +1,310 @@
+import { type BigIntStats } from "node:fs";
+export declare const CODEX_NATIVE_POLICY_CAPABILITY = "host-path-allowlist-v1";
+export declare const CODEX_NATIVE_POLICY_RECEIPT_SCHEMA = "skills.codex-native-policy-acceptance/v1";
+/** Loop safety for the parent walk. It is not a policy bound on launch depth:
+ * Unix hooks run through the configured shell (`-lc`, new session), which may
+ * exec into the command or keep wrappers, so the real chain length varies. */
+export declare const CODEX_NATIVE_POLICY_ANCESTRY_SAFETY_HOPS = 64;
+export type CodexNativeHookEvent = "SessionStart" | "UserPromptSubmit";
+/** Exactly the fields the native hook emits (hook_runtime.rs, native_skill_policy_for_hook). */
+export interface CodexNativeSkillPolicy {
+    capability: typeof CODEX_NATIVE_POLICY_CAPABILITY;
+    mode: "restricted";
+    allowedHostPaths: [string];
+    nonHostSources: "disabled";
+    processId: number;
+    effectiveConfigDigest: string;
+}
+export interface CodexNativeHookEnvelope {
+    event: CodexNativeHookEvent;
+    policy: unknown;
+    sessionId: unknown;
+    /** Present on UserPromptSubmit only; SessionStart input has no turn id. */
+    turnId?: unknown;
+    /** SHA-256 of the exact hook stdin bytes, for the authenticated channel binding. */
+    hookInputSha256?: unknown;
+    /** Inherited read end of the per-hook socketpair Codex passes to the hook
+     * child, for the authenticated channel binding. Not yet named by the native
+     * contract, so the hook does not supply it today. */
+    inheritedFd?: unknown;
+}
+/** Native Codex sets this only on the current hook child; it names the
+ * inherited read end of the per-hook socketpair (draft binding contract). */
+export declare const CODEX_NATIVE_POLICY_FD_ENV = "CODEX_NATIVE_SKILL_POLICY_FD";
+/** Map one native hook input object to the adapter envelope, exactly as the
+ * Codex `hook user-prompt` path does. Undefined means the input carries no
+ * native policy or is not a SessionStart/UserPromptSubmit input, so the guard
+ * keeps today's behaviour. `inputBytes` are the exact raw stdin bytes, hashed
+ * before any decoding; `input` must have been parsed from those same bytes. */
+export declare function codexNativeHookEnvelopeFromInput(input: Record<string, unknown>, event: string, inputBytes: Buffer, inheritedFd?: string): CodexNativeHookEnvelope | undefined;
+/** Injectable so tests can supply fake lineages; production uses the OS. */
+export interface ProcessInspector {
+    platform: string;
+    arch: string;
+    /** The hook process itself. */
+    pid: number;
+    parentOf(pid: number): number | null;
+    /** Opaque start identity; two equal reads mean the same process incarnation. */
+    startTime(pid: number): string | null;
+    executablePath(pid: number): string | null;
+}
+/** Reviewed operator trust from the managed policy (`bridge.codexNativePolicy`). */
+export interface CodexNativePolicyTrust {
+    executableDigests: Readonly<Record<string, readonly string[]>>;
+}
+/** What the native helper attests over the inherited channel (draft contract). */
+export interface CodexNativePolicyAttestation {
+    schema: typeof CODEX_NATIVE_POLICY_PEER_SCHEMA;
+    peerProcessId: number;
+}
+export interface CodexNativePolicyVerification {
+    event: CodexNativeHookEvent;
+    sessionId: string;
+    turnId: string | null;
+    policy: CodexNativeSkillPolicy;
+    platform: string;
+    ancestryHops: number;
+    processStartTime: string;
+    executablePath: string;
+    executableSha256: string;
+    /** No-follow identity of the qualified executable taken before hashing; re-taken after the helper. */
+    executableWitness: ExecutableWitness;
+    bridge: {
+        path: string;
+        sha256: string;
+    };
+    attestation?: CodexNativePolicyAttestation;
+}
+export interface CodexNativePolicyAcceptedSkill {
+    path: string;
+    treeSha256: string;
+}
+export interface CodexNativePolicyAcceptance {
+    schema: typeof CODEX_NATIVE_POLICY_RECEIPT_SCHEMA;
+    acceptedAt: string;
+    event: CodexNativeHookEvent;
+    sessionId: string;
+    turnId: string | null;
+    process: {
+        id: number;
+        startTime: string;
+        executablePath: string;
+        executableSha256: string;
+        platform: string;
+    };
+    effectiveConfigDigest: string;
+    bridge: {
+        path: string;
+        sha256: string;
+    };
+    acceptedCache: CodexNativePolicyAcceptedSkill[];
+    attestation?: CodexNativePolicyAttestation;
+}
+/** Draft native helper transport: argv, bounded run, JSON attestation. */
+export declare const CODEX_NATIVE_POLICY_PEER_SCHEMA = "native-hook-policy-peer-v1";
+export declare const CODEX_NATIVE_POLICY_HELPER_TIMEOUT_MS = 5000;
+export declare const CODEX_NATIVE_POLICY_HELPER_MAX_OUTPUT_BYTES: number;
+/** Hook-deadline bounds: the helper gets min(5 s, remaining minus the margin);
+ * a first-run executable hash needs this much budget; below the minimum the
+ * adapter refuses fast instead of spawning anything. */
+export declare const CODEX_NATIVE_POLICY_DEADLINE_MARGIN_MS = 1000;
+export declare const CODEX_NATIVE_POLICY_HELPER_MIN_TIMEOUT_MS = 500;
+export declare const CODEX_NATIVE_POLICY_FIRST_HASH_BUDGET_MS = 3000;
+export interface NativePolicyHelperRequest {
+    executablePath: string;
+    fd: number;
+    expectedProcessId: number;
+    inputSha256: string;
+    timeoutMs: number;
+    maxOutputBytes: number;
+}
+export interface NativePolicyHelperResult {
+    exitCode: number | null;
+    stdout: Buffer;
+    timedOut: boolean;
+    oversized: boolean;
+}
+/** Injectable so tests can fake the helper; production spawns the verified binary. */
+export type NativePolicyHelperRunner = (request: NativePolicyHelperRequest) => NativePolicyHelperResult;
+export declare const CODEX_NATIVE_POLICY_EXECUTABLE_CACHE_SCHEMA = "skills.codex-native-policy-executable-cache/v1";
+/** No-follow identity of the qualified executable file; the only thing cached. */
+export interface ExecutableWitness {
+    dev: string;
+    ino: string;
+    size: string;
+    mtimeNs: string;
+    ctimeNs: string;
+    uid: string;
+}
+/** Absent trust is an empty set: every platform is unqualified and refuses.
+ * The pinned digests are reviewed operator configuration, never a package default. */
+export declare function parseCodexNativePolicyTrust(value: unknown): CodexNativePolicyTrust;
+/** Strict envelope parsing. Unknown keys, unknown capability, unrestricted mode
+ * and anything but the exact bridge document refuse. */
+export declare function parseCodexNativeHookEnvelope(envelope: CodexNativeHookEnvelope, bridgeDocument: string): {
+    policy: CodexNativeSkillPolicy;
+    sessionId: string;
+    turnId: string | null;
+    hookInputSha256: string | null;
+    inheritedFd: number | null;
+};
+/** The owned bridge document: a regular file, no link in any component, its
+ * real path equal to its lexical path, and exactly the bytes the guard installs. */
+export declare function verifyCodexNativeBridgeDocument(path: string, expectedContent: string, expectedSha256: string): {
+    path: string;
+    sha256: string;
+};
+/** Walk the real parent chain from the hook process to the root. The claimed
+ * consumer must appear as a strict ancestor. Only a cycle/loop guard bounds
+ * the walk; the expected launch-chain shape (which wrappers may sit between
+ * Codex and this hook) is pending from the native author and plugs in here as
+ * a predicate over the walked chain. */
+export declare function verifyCodexNativeAncestry(inspector: ProcessInspector, processId: number): {
+    hops: number;
+    chain: number[];
+    startTime: string;
+};
+export declare function hashExecutableFile(path: string): string;
+/** Accept only a regular file owned by root or the current user that neither
+ * group nor world can write. Pure over the no-follow stat so it is testable
+ * with synthetic owners. */
+export declare function assertExecutableWitnessStat(stat: Pick<BigIntStats, "isFile" | "isSymbolicLink" | "uid" | "mode" | "dev" | "ino" | "size" | "mtimeNs" | "ctimeNs">, currentUid: number): ExecutableWitness;
+/** No-follow witness of the path proc_pidpath reported: no component may be a
+ * link, and the file must satisfy assertExecutableWitnessStat. */
+export declare function executableWitness(path: string): ExecutableWitness;
+export declare function executableCachePath(dataDir: string): string;
+/** Digest of the qualified executable through the artifact-identity cache.
+ * Only (path, dev, ino, size, mtimeNs, ctimeNs, uid) -> sha256 is cached, in
+ * process and optionally in a 0600 file under the Skills data dir. A witness
+ * that changes between before and after, or differs from the cached key, is
+ * re-hashed. Policy, attestation, session and turn results are never cached. */
+export declare function qualifiedExecutableSha256(path: string, options?: {
+    dataDir?: string;
+    hasher?: (path: string) => string;
+    deadlineMs?: number; /** Test seam: the uid the cache file must be owned by (besides root). */
+    cacheOwnerUid?: number;
+}): {
+    sha256: string;
+    witness: ExecutableWitness;
+    cached: boolean;
+};
+/** Bind the claimed process to its start identity and a pinned executable
+ * digest. The pin set is reviewed operator trust; an absent or empty set for
+ * this platform means the platform is unqualified and refuses. Linux stays
+ * unqualified until its artifact is reviewed. The helper cannot attest that it
+ * is itself reviewed, so this trust stays in the managed policy. */
+export declare function verifyCodexNativeExecutable(inspector: ProcessInspector, processId: number, trust: CodexNativePolicyTrust, cache?: {
+    dataDir?: string;
+    hasher?: (path: string) => string;
+    deadlineMs?: number;
+}, expectations?: {
+    ancestryStartTime?: string;
+}): {
+    platform: string;
+    startTime: string;
+    executablePath: string;
+    executableSha256: string;
+    witness: ExecutableWitness;
+};
+/** The Skills data directory is the operator trust root: the managed policy
+ * that carries the reviewed executable digests, and the executable identity
+ * cache, must each be a regular file reached through no symlink, owned by the
+ * current user or root and writable by neither group nor world. Anything else
+ * fails the adapter closed. A writer with the same uid is outside this
+ * boundary. */
+export declare function assertOperatorTrustRoot(dataDir: string): void;
+/** Production helper runner: the verified binary, no shell, an allowlisted
+ * empty environment, cwd `/`, the inherited descriptor forwarded as fd 3, and
+ * bounded time and output. Bun.spawnSync accepts a fourth stdio entry, which
+ * dup2s that descriptor to 3 in the child (measured on bun 1.3.14). */
+export declare function runCodexNativePolicyHelper(request: NativePolicyHelperRequest): NativePolicyHelperResult;
+/** Authenticated channel binding, against the frozen native source
+ * (native-hook-policy-peer-v1; "line" numbers below index the native
+ * producer's hook-policy-peer patch as reviewed):
+ * - the hook runner creates a Unix socketpair per invocation (line 296),
+ *   forwards the receiver to the hook child (line 171) and names it in
+ *   CODEX_NATIVE_SKILL_POLICY_FD (lines 172-175, constant at line 264);
+ * - the verifier is `<codex> debug verify-hook-policy --fd <i32>
+ *   --expected-process-id <u32> --input-sha256 <hex>` (lines 88-97, dispatch
+ *   lines 102-103), dispatched in main before config, auth-home or session
+ *   setup (lines 55-58); it requires fd > 2 (line 449), a positive pid
+ *   (line 450) and a lowercase 64-hex digest (line 456);
+ * - success writes one compact JSON object to stdout followed by a newline and
+ *   exits 0 (lines 56-58): {"schema":"native-hook-policy-peer-v1",
+ *   "peerProcessId":<kernel peer pid>,"stdinSha256":<the digest>,
+ *   "policy":<the native_skill_policy the producer emitted>} (lines 546-550,
+ *   schema at line 263); any failure returns an error from main, so the
+ *   process exits non-zero with the message on stderr and nothing on stdout;
+ * - the producer hashes the exact bytes it wrote to the hook's stdin,
+ *   lowercase hex (lines 286-288), and the verifier compares it with
+ *   --input-sha256 (line 536), so the hook must hash its raw stdin bytes;
+ * - the verifier checks the kernel peer before and after a fresh random
+ *   challenge (lines 466-469, 490-491, 517-519, 526-528); Linux also
+ *   authenticates every response chunk's writer through SCM_CREDENTIALS.
+ *   A creator-pid-only binding was rejected (NO_GO: pre-exec forgery
+ *   reproduced); the fresh challenge plus actual-writer verification is the
+ *   correction.
+ * The hook forwards the descriptor to the QUALIFIED ancestor's own executable
+ * (the digest-verified path, never PATH) as fd 3, with no shell, an empty
+ * environment, cwd `/` and bounded time and output, and accepts the
+ * attestation only when every field matches. The proof is never cached:
+ * once per invocation, SessionStart included. The channel pre-check here is
+ * fstat only; the socket semantics are enforced by the verifier itself. */
+export declare function verifyCodexNativeChannelBinding(options: {
+    executablePath: string;
+    inheritedFd: number | null;
+    expectedProcessId: number;
+    expectedStartTime: string;
+    expectedWitness?: ExecutableWitness;
+    inputSha256: string | null;
+    emittedPolicy: unknown;
+    inspector: ProcessInspector;
+    runner?: NativePolicyHelperRunner;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    deadlineMs?: number;
+}): CodexNativePolicyAttestation;
+/** Required acceptance gate: the authenticated channel binding of the native
+ * contract, run with the qualified ancestor's verified executable and its
+ * witness, its start time, the raw stdin digest, the inherited descriptor, the
+ * emitted policy and the remaining hook budget. */
+export declare function assertAuthenticatedChannelBinding(binding: {
+    processId: number;
+    hookInputSha256: string | null;
+    inheritedFd: number | null;
+    verification: CodexNativePolicyVerification;
+    emittedPolicy: unknown;
+    inspector: ProcessInspector;
+    runner?: NativePolicyHelperRunner;
+    deadlineMs?: number;
+}): CodexNativePolicyAttestation;
+/** Full adapter verification. Every step refuses with a reason. Order: trust
+ * configuration, envelope, bridge, ancestry, executable digest (reviewed trust),
+ * then the authenticated channel binding, once per invocation. */
+export declare function verifyCodexNativeSkillPolicy(options: {
+    envelope: CodexNativeHookEnvelope;
+    bridgeDocument: string;
+    expectedBridgeContent: string;
+    expectedBridgeSha256: string;
+    trust?: unknown;
+    inspector?: ProcessInspector;
+    dataDir?: string;
+    executableHasher?: (path: string) => string;
+    helperRunner?: NativePolicyHelperRunner;
+    deadlineMs?: number;
+}): CodexNativePolicyVerification;
+/** Darwin: libproc through bun:ffi. proc_pidinfo(PROC_PIDTBSDINFO) yields the
+ * parent pid and start time; proc_pidpath yields the executable path. Layout
+ * from the SDK's sys/proc_info.h (struct proc_bsdinfo, 136 bytes): pbi_pid at
+ * 12, pbi_ppid at 16, pbi_start_tvsec at 120, pbi_start_tvusec at 128. */
+export declare function darwinProcessInspector(): ProcessInspector;
+/** Linux: procfs. The parent pid and start time (clock ticks since boot) come
+ * from /proc/<pid>/stat after the bracketed command name; the executable from
+ * /proc/<pid>/exe. Linux remains unqualified until its artifact is reviewed. */
+export declare function linuxProcessInspector(): ProcessInspector;
+export declare function defaultProcessInspector(): ProcessInspector;
+export declare function codexNativePolicyReceiptPath(dataDir: string): string;
+/** Write the provenance receipt for one accepted hook: mode 0600, exclusive
+ * no-follow temporary file, then rename. Any failure throws, and the caller
+ * treats that as a refusal. Reachable only after the channel binding passes. */
+export declare function recordCodexNativePolicyAcceptance(dataDir: string, verification: CodexNativePolicyVerification, accepted: readonly CodexNativePolicyAcceptedSkill[]): string;

package/dist/lib/codex-native-trust.d.ts

@@ -0,0 +1,49 @@
+import { type AgentIntegrationPlan } from "./agent-integration.js";
+export declare const CODEX_NATIVE_TRUST_PLAN_SCHEMA = "skills.codex-native-trust-plan/v1";
+export declare const CODEX_NATIVE_TRUST_RECEIPT_SCHEMA = "skills.codex-native-trust-receipt/v1";
+export interface CodexNativeTrustPlan {
+    schema: typeof CODEX_NATIVE_TRUST_PLAN_SCHEMA;
+    dataDir: string;
+    policyPath: string;
+    platform: string;
+    digestsBefore: string[];
+    digestsAfter: string[];
+    policySha256Before: string;
+    policySha256After: string;
+    /** The ordinary plan the existing apply path writes: at most one change, the managed policy. */
+    plan: AgentIntegrationPlan;
+}
+export interface CodexNativeTrustReceipt {
+    schema: typeof CODEX_NATIVE_TRUST_RECEIPT_SCHEMA;
+    applied: boolean;
+    platform: string;
+    digestsBefore: string[];
+    digestsAfter: string[];
+    policySha256Before: string;
+    policySha256After: string;
+    changes: string[];
+    backup?: {
+        path: string;
+        sha256: string;
+        verified: true;
+    };
+    readback?: {
+        policySha256: string;
+        digests: string[];
+        verified: true;
+    };
+}
+/** Validate the request, the current policy and its SHA, and build the plan. Read-only. */
+export declare function planCodexNativeTrust(options: {
+    dataDir?: string;
+    platform: string;
+    digests: readonly string[];
+    expectedPolicySha256: string;
+}): CodexNativeTrustPlan;
+export declare function previewCodexNativeTrust(plan: CodexNativeTrustPlan): CodexNativeTrustReceipt;
+/** Write the planned trust. The current bytes are re-checked against the
+ * expected SHA immediately before the existing apply path replaces them; that
+ * path compares the exact bytes again, backs the original up, replaces the
+ * file atomically at 0600 and restores the original on failure. The backup
+ * and the result are read back and verified before a receipt is returned. */
+export declare function applyCodexNativeTrust(plan: CodexNativeTrustPlan, expectedPolicySha256: string): CodexNativeTrustReceipt;

package/dist/lib/codex-plugin-skill-controls.d.ts

@@ -32,6 +32,19 @@ export interface CodexPluginSourceInput {
     sourceSha256: string;
 }
 type Read = (path: string) => string;
+export interface CodexPluginCacheDocumentIdentity {
+    name: string;
+    namespace: string;
+    pluginId: string;
+    pluginParent: string;
+    root: string;
+    manifestSha256: string;
+}
+/** Classify one cache document as installed-plugin content through the same
+ * manifest identity, capability review and real-path binding the reviewed
+ * predicates use. This is identity only: it consults no enable rule, reviewed
+ * control or native catalog, and it never admits anything by itself. */
+export declare function classifyCodexPluginCacheDocument(document: string, cache: string, read: Read): CodexPluginCacheDocumentIdentity | null;
 /** Establish the reviewed denial/skills-only role for an exact remote parent.
  * Walk every ancestor: a dangling alias or non-directory is never absence. */
 export declare function reviewedDisabledCodexPluginParent(cache: string, parent: string, controls: CodexPluginSkillControl[], rules: unknown): boolean;