@sayknow-cli/natives 0.3.16 → 0.4.0

package/native/index.d.ts

@@ -12,6 +12,7 @@ export declare class ComputerController {
   keypress(expectedEpoch: number | undefined | null, keys: Array<string>): void
   wait(expectedEpoch: number | undefined | null, ms: number): void
 }
+
 /**
  * Long-lived macOS appearance observer.
  *
@@ -51,6 +52,18 @@ export declare class MacOSPowerAssertion {
   stop(): void
 }
 
+/** Retained no-follow authority for the SDK publication namespace. */
+export declare class NativeRetainedBrokerPublication {
+  observe(): NativeBrokerPublicationObservation
+  heartbeat(heartbeatAt: string): NativeBrokerPublicationOperation
+  sync(): NativeBrokerPublicationOperation
+  /**
+   * Close discovery, owner record, lock directory, and SDK root in that
+   * order.
+   */
+  close(): NativeBrokerPublicationOperation
+}
+
 /**
  * In-process, session-independent lifecycle **control** server exposed to TS.
  *
@@ -273,6 +286,82 @@ export declare class PtySession {
   kill(): void
 }
 
+/** Retained trusted-root authority for Linux recovery artifacts. */
+export declare class RecoveryFsRoot {
+  /** Return the stable identity of the retained root descriptor. */
+  identity(): RecoveryFsResult
+  /**
+   * Derive a retained child-directory capability from this root and exact
+   * identity evidence.
+   */
+  retainManagedDirectory(relativePath: string, expectedDev: string, expectedIno: string): RecoveryFsRoot
+  /** Stat one existing regular, single-linked file without following links. */
+  stat(relativePath: string): RecoveryFsResult
+  /** Read one existing regular, single-linked file without following links. */
+  read(relativePath: string, maxBytes: number): RecoveryFsResult
+  /** Read one managed artifact with the managed-storage size bound. */
+  readManaged(relativePath: string): RecoveryFsResult
+  /**
+   * Create one previously absent regular, owner-only file and synchronously
+   * persist its contents. Existing entries are never replaced.
+   */
+  create(relativePath: string, data: Uint8Array): RecoveryFsResult
+  /** Create one managed artifact with the managed-storage size bound. */
+  createManaged(relativePath: string, data: Uint8Array): RecoveryFsResult
+  /**
+   * Atomically replace one exact regular file with a newly written managed
+   * artifact. The destination must retain the supplied identity throughout
+   * authorization.
+   */
+  replaceManaged(relativePath: string, data: Uint8Array, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  /**
+   * Synchronously append one record to an exact retained managed file without
+   * replacing its inode or creating recovery copies.
+   */
+  appendManaged(relativePath: string, data: Uint8Array, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  /** Remove one exact managed regular file through retained authority. */
+  removeManaged(relativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  /**
+   * Create each absent directory component beneath the retained root with
+   * owner-only security. Existing components are re-opened no-follow.
+   */
+  ensureManagedDirectory(relativePath: string): RecoveryFsResult
+  /**
+   * Move an exact managed file to an absent name entirely beneath this
+   * retained root. The source identity is rechecked after the no-replace
+   * rename, and the move is rolled back on a mismatch.
+   */
+  renameManagedFileNoReplace(sourceRelativePath: string, destinationRelativePath: string, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedCtimeNs: string, expectedSha256: string): RecoveryFsResult
+  /** Snapshot a managed directory tree entirely through the retained root. */
+  snapshotManagedTree(relativePath: string): NativeDirectoryTreeResult
+  /**
+   * Move an exact managed directory tree to an absent name through retained
+   * authority.
+   */
+  renameManagedTreeNoReplace(sourceRelativePath: string, destinationRelativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsResult
+  /** Remove an exact managed directory tree through retained authority. */
+  removeManagedTree(relativePath: string, expected: NativeDirectoryTreeSnapshot): RecoveryFsResult
+  /**
+   * Atomically install an already-created regular file at an absent name.
+   * Both names remain relative to this retained root and are never resolved
+   * through a pathname after their parent descriptors are acquired.
+   */
+  install(sourceRelativePath: string, destinationRelativePath: string): RecoveryFsResult
+  /**
+   * Synchronize the retained root directory, making a preceding create or
+   * install durable when the filesystem supports directory fsync.
+   */
+  fsync(): RecoveryFsResult
+  /**
+   * Fsync one expected object relative to the retained root and prove
+   * identity.
+   */
+  fsyncExpected(relativePath: string, directory: boolean, expectedDev: string, expectedIno: string, expectedSize: string, expectedMtimeNs: string, expectedSha256?: string | undefined | null): RecoveryFsResult
+  /** Verify owner-only directory security on the retained root descriptor. */
+  verifyOwnerOnlyDirectory(): RecoveryFsResult
+  close(): RecoveryFsResult
+}
+
 /** Persistent brush-core shell session. */
 export declare class Shell {
   /**
@@ -315,7 +404,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV0_3_16(): void
+export declare function __piNativesV0_4_0(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
@@ -326,6 +415,15 @@ export declare function __piNativesV0_3_16(): void
  */
 export declare function applyBashFixups(command: string): BashFixupResult
 
+/**
+ * Apply owner-only security to the exact caller descriptor and its retained
+ * no-follow path. The descriptor is duplicated with close-on-exec and is never
+ * returned to JavaScript.
+ */
+export declare function applyOwnerOnlyFdSecurity(path: string, kind: "directory" | "file", callerFd: number): NativeOwnerOnlySecurityResult
+
+export declare function applyOwnerOnlyPathSecurity(path: string, kind: "directory" | "file"): NativeOwnerOnlySecurityResult
+
 /** Typed terminal acknowledgement result returned by acknowledgement promises. */
 export interface AskSelectedAckOutcomeEvent {
   status: string
@@ -535,6 +633,8 @@ export interface BuildInfo {
   languageSet: string
 }
 
+export declare function canonicalExistingDirectoryIdentity(path: string | Uint8Array): NativeCanonicalDirectoryIdentity
+
 /** Clipboard image payload encoded as PNG bytes. */
 export interface ClipboardImage {
   /** PNG-encoded image bytes. */
@@ -647,6 +747,29 @@ export declare enum Ellipsis {
  */
 export declare function encodeSixel(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number): string
 
+/**
+ * Remove an already durably planned detached directory only when a fresh
+ * descriptor-relative snapshot exactly equals the persisted snapshot. The
+ * caller-planned root remains in place while its opened descriptor is
+ * authoritative throughout recursive removal.
+ */
+export declare function exactRemoveDirectoryTree(path: string, snapshot: NativeDirectoryTreeSnapshot): NativeExactUnlinkResult
+
+/**
+ * Restore only the detached object that still has the supplied platform
+ * identity. The detached and original paths must retain the same validated
+ * parent, and restoration never replaces an existing original path.
+ */
+export declare function exactRestore(detachedPath: string, originalPath: string, identity: NativeExactFileIdentity): NativeExactUnlinkResult
+
+/**
+ * Delete only the regular file that still has the supplied platform identity.
+ *
+ * This never follows a symlink or reparse point in the target path and reports
+ * validation failures as typed results rather than deleting a replacement.
+ */
+export declare function exactUnlink(path: string, identity: NativeExactFileIdentity): NativeExactUnlinkResult
+
 /**
  * Execute a brush shell command.
  *
@@ -1377,8 +1500,209 @@ export interface MinimizerResult {
   outputBytes: number
 }
 
+/** Evidence for one Linux POSIX ACL attribute. */
+export interface NativeAclAttributeEvidence {
+  clear: string
+  query: string
+}
+
+/** Bounded Linux POSIX ACL evidence for an owner-only result. */
+export interface NativeAclEvidence {
+  access: NativeAclAttributeEvidence
+  default?: NativeAclAttributeEvidence
+}
+
+/** Classification of a read-only retained-publication observation. */
+export interface NativeBrokerPublicationObservation {
+  kind: string
+}
+
+/** Result of a retained positional heartbeat write or sync. */
+export interface NativeBrokerPublicationOperation {
+  kind: string
+}
+
 export declare function nativeBuildInfo(): BuildInfo
 
+/** Result of resolving an existing directory to its stable platform identity. */
+export type NativeCanonicalDirectoryIdentity =
+	| { ok: true; platform: "posix" | "win32"; canonicalPath: string; code?: never }
+	| {
+			ok: false;
+			platform?: never;
+			canonicalPath?: never;
+			code: "not_found" | "not_directory" | "not_utf8" | "network_unsupported" | "identity_unavailable" | "io_error";
+	  }
+
+/**
+ * A deterministic, no-follow description of a directory tree. `relative_path`
+ * is UTF-8, uses `/` separators, and is empty only for the root entry.
+ */
+export interface NativeDirectoryTreeEntry {
+  relativePath: string
+  kind: string
+  dev: string
+  ino: string
+  size: string
+  mtimeNs: string
+  ctimeNs: string
+  sha256?: string
+}
+
+export interface NativeDirectoryTreeResult {
+  ok: boolean
+  code?: string
+  snapshot?: NativeDirectoryTreeSnapshot
+}
+
+/**
+ * Stable evidence returned by `snapshot_directory_tree` and consumed verbatim
+ * by `exact_remove_directory_tree`.
+ */
+export interface NativeDirectoryTreeSnapshot {
+  rootDev: string
+  rootIno: string
+  entries: Array<NativeDirectoryTreeEntry>
+}
+
+/**
+ * Caller-supplied identity and preauthorized quarantine evidence for exact
+ * deletion.
+ */
+export interface NativeExactFileIdentity {
+  dev: bigint
+  ino: bigint
+  size: bigint
+  mtimeNs: bigint
+  /**
+   * When true, atomically detach a directory rather than deleting a regular
+   * file.
+   */
+  directory?: boolean
+  /**
+   * Keep a regular file in quarantine after its identity has been verified
+   * instead of unlinking it. This makes cross-device retirement recoverable.
+   */
+  detachOnly?: boolean
+  /**
+   * A caller-persisted, single-component no-replace quarantine destination.
+   * Required for every exact deletion so authority survives a post-detach
+   * crash.
+   */
+  quarantineName?: string
+  /**
+   * SHA-256 of regular-file bytes. Required for regular-file deletion and
+   * verified from the detached object before unlinking it.
+   */
+  sha256?: string
+}
+
+/** Typed result of an identity-bound regular-file deletion or directory detach. */
+export interface NativeExactUnlinkResult {
+  ok: boolean
+  code?: string
+  detachedPath?: string
+  retainedSuccessorPath?: string
+  /**
+   * An internal exchange-placeholder cleanup entry retained after cleanup
+   * could not complete. This is never a canonical publisher successor and
+   * remains recoverable only at this path.
+   */
+  retainedPlaceholderPath?: string
+  /**
+   * A retained cleanup entry whose identity could not be verified. This is
+   * neither a stale detached object nor a publisher successor.
+   */
+  retainedUnknownPath?: string
+}
+
+/** Result of applying or checking owner-only path security. */
+export type NativeOwnerOnlySecurityResult =
+	| {
+			ok: true;
+			platform: "linux";
+			kind: "file";
+			protocol: "apply" | "verify";
+			aclEvidence: {
+				access: {
+					clear: "cleared" | "already_absent" | "unsupported" | "not_run";
+					query: "absent" | "unsupported";
+				};
+				default?: never;
+			};
+			code?: never;
+			operation?: never;
+			attribute?: never;
+	  }
+	| {
+			ok: true;
+			platform: "linux";
+			kind: "directory";
+			protocol: "apply" | "verify";
+			aclEvidence: {
+				access: {
+					clear: "cleared" | "already_absent" | "unsupported" | "not_run";
+					query: "absent" | "unsupported";
+				};
+				default: {
+					clear: "cleared" | "already_absent" | "unsupported" | "not_run";
+					query: "absent" | "unsupported";
+				};
+			};
+			code?: never;
+			operation?: never;
+			attribute?: never;
+	  }
+	| {
+			ok: true;
+			platform?: never;
+			kind?: never;
+			protocol?: never;
+			aclEvidence?: never;
+			code?: never;
+			operation?: never;
+			attribute?: never;
+	  }
+	| {
+			ok: false;
+			code: "acl_denied" | "acl_io_error" | "acl_present" | "acl_malformed" | "acl_unknown";
+			operation: "clear" | "query";
+			attribute: "access" | "default";
+			platform?: never;
+			kind?: never;
+			protocol?: never;
+			aclEvidence?: never;
+	  }
+	| {
+			ok: false;
+			code: "acl_unavailable" | "acl_apply_failed" | "acl_verify_failed";
+			operation?: never;
+			attribute?: never;
+			platform?: never;
+			kind?: never;
+			protocol?: never;
+			aclEvidence?: never;
+	  }
+	| {
+			ok: false;
+			code:
+				| "not_found"
+				| "not_directory"
+				| "network_unsupported"
+				| "reparse_point"
+				| "identity_unavailable"
+				| "identity_mismatch"
+				| "owner_mismatch"
+				| "mode_mismatch"
+				| "io_error";
+			operation?: never;
+			attribute?: never;
+			platform?: never;
+			kind?: never;
+			protocol?: never;
+			aclEvidence?: never;
+	  }
+
 /** Bound endpoint info returned from [`NotificationServer::start`]. */
 export interface NotificationEndpoint {
   /** Bind host (loopback). */
@@ -1391,6 +1715,12 @@ export interface NotificationEndpoint {
   sessionId: string
 }
 
+/**
+ * Acquire an immutable trusted-root descriptor. Linux is required; every
+ * other platform returns a durable unsupported-platform result.
+ */
+export declare function openRecoveryFsRoot(path: string): RecoveryFsRoot
+
 /** Parsed Kitty keyboard protocol sequence result for a Kitty input sequence. */
 export interface ParsedKittyResult {
   /** Primary codepoint associated with the key. */
@@ -1495,9 +1825,27 @@ export declare function ptyTimeoutCount(): bigint
  */
 export declare function readImageFromClipboard(): Promise<ClipboardImage | undefined | null>
 
+export interface RecoveryFsIdentity {
+  dev: string
+  ino: string
+  size: string
+  mtimeNs: string
+  ctimeNs: string
+  sha256?: string
+}
+
+export interface RecoveryFsResult {
+  ok: boolean
+  code?: string
+  identity?: RecoveryFsIdentity
+  data?: Uint8Array
+}
+
+export declare function renameNoReplacePath(sourcePath: string, destinationPath: string): NativeExactUnlinkResult
+
 /** A client reply forwarded to the TypeScript host for gate resolution. */
 export interface ReplyEvent {
-  /** The action id being answered (the real broker `gate_id` for asks). */
+  /** The transient action/presentation id being answered, not a durable gate id. */
   id: string
   /** JSON-encoded `ReplyAnswer` (number, string, or `{selected,custom}`). */
   answerJson: string
@@ -1507,6 +1855,12 @@ export interface ReplyEvent {
   replyReceiptId: string
 }
 
+/**
+ * Retain the existing no-follow SDK publication objects after one-time
+ * publication.
+ */
+export declare function retainBrokerPublication(agentDir: string): NativeRetainedBrokerPublication
+
 /**
  * Search content for a pattern (one-shot, compiles pattern each time).
  * For repeated searches with the same pattern, use [`grep`] with file filters.
@@ -1636,6 +1990,13 @@ export interface SliceResult {
  */
 export declare function sliceWithWidth(line: string, startCol: number, length: number, strict: boolean | undefined | null, tabWidth: number): SliceResult
 
+/**
+ * Capture a deterministic, descriptor-relative snapshot of a regular-file and
+ * directory-only tree. Symlinks, special files, non-UTF-8 names, and topology
+ * changes are rejected rather than followed.
+ */
+export declare function snapshotDirectoryTree(path: string): NativeDirectoryTreeResult
+
 export declare function summarizeCode(options: SummaryOptions): SummaryResult
 
 export interface SummaryOptions {
@@ -1687,6 +2048,15 @@ export declare function truncateLinesToWidth(lines: Array<string>, maxWidth: num
 
 export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind: Ellipsis | undefined | null, pad: boolean | undefined | null, tabWidth: number): string
 
+/**
+ * Verify owner-only security for the exact caller descriptor and retained
+ * no-follow path. The descriptor is duplicated with close-on-exec and is never
+ * returned to JavaScript.
+ */
+export declare function verifyOwnerOnlyFdSecurity(path: string, kind: "directory" | "file", callerFd: number): NativeOwnerOnlySecurityResult
+
+export declare function verifyOwnerOnlyPathSecurity(path: string, kind: "directory" | "file"): NativeOwnerOnlySecurityResult
+
 /**
  * Calculate visible width of text, excluding ANSI escape sequences.
  *

package/native/index.js

@@ -20,22 +20,30 @@ nativeBindings.initNativeCrashDiagnostics?.();
 export const ComputerController = nativeBindings.ComputerController;
 export const MacAppearanceObserver = nativeBindings.MacAppearanceObserver;
 export const MacOSPowerAssertion = nativeBindings.MacOSPowerAssertion;
+export const NativeRetainedBrokerPublication = nativeBindings.NativeRetainedBrokerPublication;
 export const NotificationControlServer = nativeBindings.NotificationControlServer;
 export const NotificationServer = nativeBindings.NotificationServer;
 export const Process = nativeBindings.Process;
 export const PtySession = nativeBindings.PtySession;
+export const RecoveryFsRoot = nativeBindings.RecoveryFsRoot;
 export const Shell = nativeBindings.Shell;
 
 // functions
-export const __piNativesV0_3_16 = nativeBindings.__piNativesV0_3_16;
+export const __piNativesV0_4_0 = nativeBindings.__piNativesV0_4_0;
 export const applyBashFixups = nativeBindings.applyBashFixups;
+export const applyOwnerOnlyFdSecurity = nativeBindings.applyOwnerOnlyFdSecurity;
+export const applyOwnerOnlyPathSecurity = nativeBindings.applyOwnerOnlyPathSecurity;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;
+export const canonicalExistingDirectoryIdentity = nativeBindings.canonicalExistingDirectoryIdentity;
 export const computerScreenshot = nativeBindings.computerScreenshot;
 export const copyToClipboard = nativeBindings.copyToClipboard;
 export const detectMacOSAppearance = nativeBindings.detectMacOSAppearance;
 export const diffLines = nativeBindings.diffLines;
 export const encodeSixel = nativeBindings.encodeSixel;
+export const exactRemoveDirectoryTree = nativeBindings.exactRemoveDirectoryTree;
+export const exactRestore = nativeBindings.exactRestore;
+export const exactUnlink = nativeBindings.exactUnlink;
 export const executeShell = nativeBindings.executeShell;
 export const extractSegments = nativeBindings.extractSegments;
 export const fuzzyFind = nativeBindings.fuzzyFind;
@@ -63,16 +71,22 @@ export const matchesKey = nativeBindings.matchesKey;
 export const matchesKittySequence = nativeBindings.matchesKittySequence;
 export const matchesLegacySequence = nativeBindings.matchesLegacySequence;
 export const nativeBuildInfo = nativeBindings.nativeBuildInfo;
+export const openRecoveryFsRoot = nativeBindings.openRecoveryFsRoot;
 export const parseKey = nativeBindings.parseKey;
 export const parseKittySequence = nativeBindings.parseKittySequence;
 export const ptyTimeoutCount = nativeBindings.ptyTimeoutCount;
 export const readImageFromClipboard = nativeBindings.readImageFromClipboard;
+export const renameNoReplacePath = nativeBindings.renameNoReplacePath;
+export const retainBrokerPublication = nativeBindings.retainBrokerPublication;
 export const search = nativeBindings.search;
 export const sliceWithWidth = nativeBindings.sliceWithWidth;
+export const snapshotDirectoryTree = nativeBindings.snapshotDirectoryTree;
 export const summarizeCode = nativeBindings.summarizeCode;
 export const supportsLanguage = nativeBindings.supportsLanguage;
 export const truncateLinesToWidth = nativeBindings.truncateLinesToWidth;
 export const truncateToWidth = nativeBindings.truncateToWidth;
+export const verifyOwnerOnlyFdSecurity = nativeBindings.verifyOwnerOnlyFdSecurity;
+export const verifyOwnerOnlyPathSecurity = nativeBindings.verifyOwnerOnlyPathSecurity;
 export const visibleWidth = nativeBindings.visibleWidth;
 export const visibleWidths = nativeBindings.visibleWidths;
 export const wrapTextWithAnsi = nativeBindings.wrapTextWithAnsi;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sayknow-cli/natives",
-	"version": "0.3.16",
+	"version": "0.4.0",
 	"description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://sayknow-cli.com",