@gajae-code/natives 0.11.3 → 0.11.5

package/native/index.d.ts

@@ -1,5 +1,12 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/**
+ * macOS computer-use controller.
+ *
+ * This declaration and the named JS export are available on every platform so
+ * consumers can import them portably; the native controller itself is built
+ * only on macOS.
+ */
 export declare class ComputerController {
   constructor()
   screenshot(): ComputerScreenshot
@@ -52,6 +59,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.
  *
@@ -288,6 +307,15 @@ export declare class Process {
   get ppid(): number | null
   /** Launch arguments for this process. */
   args(): Array<string>
+  /**
+   * Send `signal` only to this pinned process reference.
+   *
+   * On Linux this uses the owned pidfd; on Windows it uses the owned process
+   * handle. It deliberately never discovers descendants or signals a process
+   * group. Returns `false` when the pinned process has already exited or the
+   * operating system rejects delivery.
+   */
+  signalRoot(signal: number): boolean
   /**
    * Send `signal` to this process and its descendants, children first.
    *
@@ -331,6 +359,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 {
   /**
@@ -373,7 +477,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV0_11_3(): void
+export declare function __piNativesV0_11_5(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
@@ -384,6 +488,13 @@ export declare function __piNativesV0_11_3(): 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. */
@@ -1500,6 +1611,28 @@ 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. */
@@ -1523,6 +1656,7 @@ export interface NativeDirectoryTreeEntry {
   ino: string
   size: string
   mtimeNs: string
+  ctimeNs: string
   sha256?: string
 }
 
@@ -1579,11 +1713,87 @@ 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; code?: never }
+	| {
+			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:
@@ -1591,12 +1801,17 @@ export type NativeOwnerOnlySecurityResult =
 				| "not_directory"
 				| "network_unsupported"
 				| "reparse_point"
-				| "acl_unavailable"
-				| "acl_apply_failed"
-				| "acl_verify_failed"
 				| "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`]. */
@@ -1611,6 +1826,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. */
@@ -1727,6 +1948,22 @@ 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. */
@@ -1744,6 +1981,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
+
 /** Public status of exact direct retirement. Claims and receipts remain native. */
 export interface RetireIfUnclaimedResult {
   status: 'retired' | 'already_terminal' | 'claimed' | 'stale'
@@ -1942,6 +2185,13 @@ 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
 
 /**

package/native/index.js

@@ -20,15 +20,18 @@ 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_11_3 = nativeBindings.__piNativesV0_11_3;
+export const __piNativesV0_11_5 = nativeBindings.__piNativesV0_11_5;
 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;
@@ -68,11 +71,13 @@ 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;
@@ -80,6 +85,7 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gajae-code/natives",
-	"version": "0.11.3",
+	"version": "0.11.5",
 	"description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://gajae-code.com",
@@ -61,11 +61,11 @@
 		"README.md"
 	],
 	"optionalDependencies": {
-		"@gajae-code/natives-darwin-arm64": "0.11.3",
-		"@gajae-code/natives-darwin-x64": "0.11.3",
-		"@gajae-code/natives-linux-arm64": "0.11.3",
-		"@gajae-code/natives-linux-x64": "0.11.3",
-		"@gajae-code/natives-win32-x64": "0.11.3"
+		"@gajae-code/natives-darwin-arm64": "0.11.5",
+		"@gajae-code/natives-darwin-x64": "0.11.5",
+		"@gajae-code/natives-linux-arm64": "0.11.5",
+		"@gajae-code/natives-linux-x64": "0.11.5",
+		"@gajae-code/natives-win32-x64": "0.11.5"
 	},
 	"exports": {
 		".": {