@struktoai/mirage-node 0.0.5-alpha.1 → 0.0.6

package/dist/secrets/constants.js

@@ -0,0 +1,58 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { createRequire } from 'node:module';
+import { SecretsError } from '@struktoai/mirage-core/secrets/errors';
+import { registerSecrets } from '@struktoai/mirage-core/secrets/registry';
+import { AWSSMConfig, DotenvConfig, EnvConfig, OnePasswordConfig } from "./config.js";
+// Resolution only, never a load: this answers whether an optional
+// peer is installed without pulling it in. `import.meta.resolve` would
+// be the obvious tool and is unusable -- vitest's SSR transform leaves
+// it undefined, so the probe would report every peer missing under
+// test and in any bundler that does the same.
+const resolvePeer = createRequire(import.meta.url).resolve;
+/**
+ * Refuse a source whose optional peer dependency is not installed.
+ *
+ * Synchronous, so it answers where the workspace is built rather than
+ * on the first line that reads a secret.
+ */
+function requirePeer(source, peer) {
+    try {
+        resolvePeer(peer);
+    }
+    catch {
+        throw new SecretsError(`the '${source}' source needs its optional dependency (${peer}): npm install ${peer}`);
+    }
+}
+/** The builtin source names this module registers, sorted. */
+export const BUILTIN_SOURCE_NAMES = ['1password', 'aws-sm', 'dotenv', 'env'];
+// Builtin fetchers load lazily: each registered fetch dynamically
+// imports its module on first use, so a source's SDK loads only when a
+// workspace actually uses it (Python spells the same table as import
+// paths beside its core registry). Registration itself runs at import
+// time -- the compression-codec pattern -- because core's registry
+// cannot name node modules; the node Workspace and the config door both
+// import this module, so either entry point arms the builtins.
+registerSecrets('env', EnvConfig, async (config, ref) => (await import("./env.js")).fetchEnv(config, ref));
+registerSecrets('dotenv', DotenvConfig, async (config, ref) => (await import("./dotenv.js")).fetchDotenv(config, ref));
+registerSecrets('aws-sm', AWSSMConfig, async (config, ref) => (await import("./aws.js")).fetchAwsSm(config, ref));
+registerSecrets('1password', OnePasswordConfig, async (config, ref) => (await import("./onepassword.js")).fetchOnePassword(config, ref), 
+// The SDK still loads lazily; this only asks the resolver whether it
+// is installed, so a workspace that declares the source learns at
+// construction and one that does not pays nothing. Python's own
+// check is its `source_for` resolving an import path.
+() => {
+    requirePeer('1password', '@1password/sdk');
+});
+//# sourceMappingURL=constants.js.map

package/dist/secrets/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/secrets/constants.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAA;AAEzE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAErF,kEAAkE;AAClE,uEAAuE;AACvE,uEAAuE;AACvE,mEAAmE;AACnE,8CAA8C;AAC9C,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAA;AAE1D;;;;;GAKG;AACH,SAAS,WAAW,CAAC,MAAc,EAAE,IAAY;IAC/C,IAAI,CAAC;QACH,WAAW,CAAC,IAAI,CAAC,CAAA;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,YAAY,CACpB,QAAQ,MAAM,2CAA2C,IAAI,kBAAkB,IAAI,EAAE,CACtF,CAAA;IACH,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAA;AAErF,kEAAkE;AAClE,uEAAuE;AACvE,qEAAqE;AACrE,sEAAsE;AACtE,mEAAmE;AACnE,wEAAwE;AACxE,+DAA+D;AAC/D,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CACtD,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CACjD,CAAA;AACD,eAAe,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAC5D,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CACvD,CAAA;AACD,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAC3D,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CACnD,CAAA;AACD,eAAe,CACb,WAAW,EACX,iBAAiB,EACjB,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC;AACvF,qEAAqE;AACrE,kEAAkE;AAClE,gEAAgE;AAChE,sDAAsD;AACtD,GAAG,EAAE;IACH,WAAW,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAA;AAC5C,CAAC,CACF,CAAA"}

package/dist/secrets/dotenv.d.ts

@@ -0,0 +1,13 @@
+import type { ResolvedSecret } from '@struktoai/mirage-core/secrets/types';
+import type { DotenvConfig } from './config.ts';
+/**
+ * Read one dotenv file as one secret: the file's key=value pairs as
+ * fields. `ref` is the host filesystem path of the file; empty falls
+ * back to `config.path`. A missing file is a SecretsError naming the
+ * path. Values are taken verbatim: `dotenv.parse` never interpolates,
+ * and Python passes `interpolate=False` to match, so a `${NAME}` in a
+ * value stays literal in both languages instead of copying a host
+ * variable into a secret.
+ */
+export declare function fetchDotenv(config: DotenvConfig, ref: string): Promise<ResolvedSecret>;
+//# sourceMappingURL=dotenv.d.ts.map

package/dist/secrets/dotenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv.d.ts","sourceRoot":"","sources":["../../src/secrets/dotenv.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAA;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAY5F"}

package/dist/secrets/dotenv.js

@@ -0,0 +1,40 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { readFile } from 'node:fs/promises';
+import { parse } from 'dotenv';
+import { SecretsError } from '@struktoai/mirage-core/secrets/errors';
+/**
+ * Read one dotenv file as one secret: the file's key=value pairs as
+ * fields. `ref` is the host filesystem path of the file; empty falls
+ * back to `config.path`. A missing file is a SecretsError naming the
+ * path. Values are taken verbatim: `dotenv.parse` never interpolates,
+ * and Python passes `interpolate=False` to match, so a `${NAME}` in a
+ * value stays literal in both languages instead of copying a host
+ * variable into a secret.
+ */
+export async function fetchDotenv(config, ref) {
+    const path = ref !== '' ? ref : config.path;
+    let text;
+    try {
+        text = await readFile(path, 'utf-8');
+    }
+    catch (caught) {
+        if (caught.code === 'ENOENT') {
+            throw new SecretsError(`dotenv file not found: ${path}`, { cause: caught });
+        }
+        throw caught;
+    }
+    return { fields: parse(text) };
+}
+//# sourceMappingURL=dotenv.js.map

package/dist/secrets/dotenv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv.js","sourceRoot":"","sources":["../../src/secrets/dotenv.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAE3C,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAE9B,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AAKpE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAoB,EAAE,GAAW;IACjE,MAAM,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAA;IAC3C,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACtC,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,IAAK,MAA4B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpD,MAAM,IAAI,YAAY,CAAC,0BAA0B,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;QAC7E,CAAC;QACD,MAAM,MAAM,CAAA;IACd,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAA;AAChC,CAAC"}

package/dist/secrets/env.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedSecret } from '@struktoai/mirage-core/secrets/types';
+import type { EnvConfig } from './config.ts';
+/**
+ * Read the host process environment as one secret.
+ *
+ * `ref` must be empty (the process env has no sub-address); a managed
+ * entry's `key` selects the variable to read.
+ */
+export declare function fetchEnv(_config: EnvConfig, ref: string): Promise<ResolvedSecret>;
+//# sourceMappingURL=env.d.ts.map

package/dist/secrets/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/secrets/env.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAA;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAajF"}

package/dist/secrets/env.js

@@ -0,0 +1,32 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { SecretsError } from '@struktoai/mirage-core/secrets/errors';
+/**
+ * Read the host process environment as one secret.
+ *
+ * `ref` must be empty (the process env has no sub-address); a managed
+ * entry's `key` selects the variable to read.
+ */
+export function fetchEnv(_config, ref) {
+    if (ref !== '') {
+        return Promise.reject(new SecretsError(`the 'env' source takes no ref (the process env has no sub-address), got '${ref}'`));
+    }
+    const fields = {};
+    for (const [name, value] of Object.entries(process.env)) {
+        if (typeof value === 'string')
+            fields[name] = value;
+    }
+    return Promise.resolve({ fields });
+}
+//# sourceMappingURL=env.js.map

package/dist/secrets/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/secrets/env.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAA;AAKpE;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAkB,EAAE,GAAW;IACtD,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,YAAY,CACd,4EAA4E,GAAG,GAAG,CACnF,CACF,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAA2B,EAAE,CAAA;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;IACrD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;AACpC,CAAC"}

package/dist/secrets/onepassword.d.ts

@@ -0,0 +1,79 @@
+import type { Client, Item } from '@1password/sdk';
+import type { ResolvedSecret } from '@struktoai/mirage-core/secrets/types';
+import type { OnePasswordConfig } from './config.ts';
+export declare const OP_SCHEME = "op://";
+export declare const TOKEN_VAR = "OP_SERVICE_ACCOUNT_TOKEN";
+export declare const INTEGRATION_NAME = "mirage";
+export declare const NOTES_KEY = "notesPlain";
+/** A 1Password reference split into its parts. */
+export interface OpRef {
+    readonly vault: string;
+    readonly item: string;
+    /** The field label; empty for an item reference. */
+    readonly field: string;
+}
+/**
+ * Split a 1Password secret reference into vault, item and field.
+ *
+ * Both of 1Password's own ref shapes are accepted, and they mean
+ * different fetches: an item reference reads every field, so N
+ * variables out of one item cost one call, while a field reference
+ * (`op://<vault>/<item>[/<section>]/<field>`) is resolved as itself,
+ * which is what the app's "Copy Secret Reference" button hands you.
+ *
+ * Throws SecretsError on an empty ref, one that is not an `op://` url,
+ * or one naming less than a vault and an item.
+ */
+export declare function parseOpRef(ref: string): OpRef;
+/**
+ * Authenticate a 1Password SDK client.
+ *
+ * The SDK loads on first use (the lazy-module trick Python spells as
+ * an import path). Built per fetch rather than cached, because a
+ * fetched value lands on a session var and never refetches, so a cache
+ * would keep an authenticated handle alive long past the line that
+ * needed one. An absent `token` falls back to the process env, so a
+ * deployment with one account declares nothing.
+ *
+ * Throws SecretsError when neither the config nor the env carries a
+ * service account token.
+ */
+export declare function onePasswordClient(config: OnePasswordConfig): Promise<Client>;
+/**
+ * Resolve a vault's id from the name a ref spells.
+ *
+ * A ref names a vault by title, which the item API cannot take, so
+ * this is the extra call an item reference costs. An id matches too,
+ * so a deployment that pins ids never pays for the title lookup being
+ * wrong after a rename. Throws SecretsError when no vault matches.
+ */
+export declare function findVaultId(client: Client, name: string): Promise<string>;
+/**
+ * Resolve an item's id within one vault, by title or by id.
+ *
+ * Throws SecretsError when no item of that title or id is in the
+ * vault.
+ */
+export declare function findItemId(client: Client, vaultId: string, name: string): Promise<string>;
+/**
+ * Shape one item into secret fields, keyed by field label.
+ *
+ * Labels are what a ref and a managed entry's `key` both address, and
+ * 1Password fixes the built-in ones per category (an API Credential
+ * item's secret is `credential`), so they are the keys here. Two
+ * fields sharing a label in different sections is the one ambiguity,
+ * and the later one wins -- the SDK refuses such a ref outright, so
+ * neither shape promises more than the other.
+ */
+export declare function fieldsFromItem(item: Item): Record<string, string>;
+/**
+ * Fetch one secret from 1Password.
+ *
+ * A field reference is one `resolve` call and returns that field
+ * alone, keyed by its label; an item reference is a vault lookup, an
+ * item lookup and a get, and returns every field, which is what lets
+ * one AWS item fill four variables on one await. 1Password does not
+ * expire an item, so `expiresAt` stays absent.
+ */
+export declare function fetchOnePassword(config: OnePasswordConfig, ref: string): Promise<ResolvedSecret>;
+//# sourceMappingURL=onepassword.d.ts.map

package/dist/secrets/onepassword.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onepassword.d.ts","sourceRoot":"","sources":["../../src/secrets/onepassword.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AAGlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAA;AAE1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAGpD,eAAO,MAAM,SAAS,UAAU,CAAA;AAChC,eAAO,MAAM,SAAS,6BAA6B,CAAA;AACnD,eAAO,MAAM,gBAAgB,WAAW,CAAA;AAKxC,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC,kDAAkD;AAClD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAa7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAclF;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK/E;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUjE;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,iBAAiB,EACzB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,CAAC,CAOzB"}

package/dist/secrets/onepassword.js

@@ -0,0 +1,141 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { SecretsError } from '@struktoai/mirage-core/secrets/errors';
+import { VERSION } from "../version.js";
+export const OP_SCHEME = 'op://';
+export const TOKEN_VAR = 'OP_SERVICE_ACCOUNT_TOKEN';
+export const INTEGRATION_NAME = 'mirage';
+// What `op://vault/item/notesPlain` addresses: an item's note is not
+// an `ItemField`, so it is folded in under the name the ref grammar
+// gives it rather than being invisible to a `key`.
+export const NOTES_KEY = 'notesPlain';
+/**
+ * Split a 1Password secret reference into vault, item and field.
+ *
+ * Both of 1Password's own ref shapes are accepted, and they mean
+ * different fetches: an item reference reads every field, so N
+ * variables out of one item cost one call, while a field reference
+ * (`op://<vault>/<item>[/<section>]/<field>`) is resolved as itself,
+ * which is what the app's "Copy Secret Reference" button hands you.
+ *
+ * Throws SecretsError on an empty ref, one that is not an `op://` url,
+ * or one naming less than a vault and an item.
+ */
+export function parseOpRef(ref) {
+    if (ref === '') {
+        throw new SecretsError("the '1password' source needs a ref: op://<vault>/<item>");
+    }
+    if (!ref.startsWith(OP_SCHEME)) {
+        throw new SecretsError(`a '1password' ref is an op:// url, got '${ref}'`);
+    }
+    const parts = ref.slice(OP_SCHEME.length).split('/');
+    const [vault, item] = parts;
+    if (vault === undefined || item === undefined || parts.some((part) => part === '')) {
+        throw new SecretsError(`a '1password' ref names a vault and an item, got '${ref}'`);
+    }
+    return { vault, item, field: parts.length > 2 ? (parts[parts.length - 1] ?? '') : '' };
+}
+/**
+ * Authenticate a 1Password SDK client.
+ *
+ * The SDK loads on first use (the lazy-module trick Python spells as
+ * an import path). Built per fetch rather than cached, because a
+ * fetched value lands on a session var and never refetches, so a cache
+ * would keep an authenticated handle alive long past the line that
+ * needed one. An absent `token` falls back to the process env, so a
+ * deployment with one account declares nothing.
+ *
+ * Throws SecretsError when neither the config nor the env carries a
+ * service account token.
+ */
+export async function onePasswordClient(config) {
+    const token = config.token ?? process.env[TOKEN_VAR] ?? '';
+    if (token === '') {
+        throw new SecretsError("the '1password' source needs a service account token: set " +
+            `${TOKEN_VAR}, or give the source a 'token'`);
+    }
+    const { createClient } = await import('@1password/sdk');
+    return await createClient({
+        auth: token,
+        integrationName: INTEGRATION_NAME,
+        integrationVersion: VERSION,
+    });
+}
+/**
+ * Resolve a vault's id from the name a ref spells.
+ *
+ * A ref names a vault by title, which the item API cannot take, so
+ * this is the extra call an item reference costs. An id matches too,
+ * so a deployment that pins ids never pays for the title lookup being
+ * wrong after a rename. Throws SecretsError when no vault matches.
+ */
+export async function findVaultId(client, name) {
+    for (const vault of await client.vaults.list()) {
+        if (name === vault.id || name === vault.title)
+            return vault.id;
+    }
+    throw new SecretsError(`1password vault '${name}' not found`);
+}
+/**
+ * Resolve an item's id within one vault, by title or by id.
+ *
+ * Throws SecretsError when no item of that title or id is in the
+ * vault.
+ */
+export async function findItemId(client, vaultId, name) {
+    for (const item of await client.items.list(vaultId)) {
+        if (name === item.id || name === item.title)
+            return item.id;
+    }
+    throw new SecretsError(`1password item '${name}' not found`);
+}
+/**
+ * Shape one item into secret fields, keyed by field label.
+ *
+ * Labels are what a ref and a managed entry's `key` both address, and
+ * 1Password fixes the built-in ones per category (an API Credential
+ * item's secret is `credential`), so they are the keys here. Two
+ * fields sharing a label in different sections is the one ambiguity,
+ * and the later one wins -- the SDK refuses such a ref outright, so
+ * neither shape promises more than the other.
+ */
+export function fieldsFromItem(item) {
+    // Object.fromEntries, not keyed assignment: a field labelled
+    // `__proto__` would otherwise assign through the prototype setter
+    // and leave no own property for a `key` to select, where python's
+    // dict keeps the label like any other.
+    const fields = Object.fromEntries(item.fields.filter((field) => field.title !== '').map((field) => [field.title, field.value]));
+    if (item.notes !== '' && !Object.hasOwn(fields, NOTES_KEY))
+        fields[NOTES_KEY] = item.notes;
+    return fields;
+}
+/**
+ * Fetch one secret from 1Password.
+ *
+ * A field reference is one `resolve` call and returns that field
+ * alone, keyed by its label; an item reference is a vault lookup, an
+ * item lookup and a get, and returns every field, which is what lets
+ * one AWS item fill four variables on one await. 1Password does not
+ * expire an item, so `expiresAt` stays absent.
+ */
+export async function fetchOnePassword(config, ref) {
+    const { vault, item, field } = parseOpRef(ref);
+    const client = await onePasswordClient(config);
+    if (field !== '')
+        return { fields: { [field]: await client.secrets.resolve(ref) } };
+    const vaultId = await findVaultId(client, vault);
+    const itemId = await findItemId(client, vaultId, item);
+    return { fields: fieldsFromItem(await client.items.get(vaultId, itemId)) };
+}
+//# sourceMappingURL=onepassword.js.map

package/dist/secrets/onepassword.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onepassword.js","sourceRoot":"","sources":["../../src/secrets/onepassword.ts"],"names":[],"mappings":"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"}

package/dist/shell/console/redis/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const APPEND_LUA: string;
+export declare const POLL_MS = 100;
+//# sourceMappingURL=constants.d.ts.map

package/dist/shell/console/redis/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/shell/console/redis/constants.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,UAAU,QAAiE,CAAA;AAExF,eAAO,MAAM,OAAO,MAAM,CAAA"}

package/dist/shell/console/redis/constants.js

@@ -0,0 +1,22 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { readFileSync } from 'node:fs';
+// INCR hands out the dense seq and XADD stores the chunk under the
+// stream id `(seq+1)-0` in one atomic step, so two appends racing (a
+// kill marker against a runner's last emit) cannot collide on an id.
+// Shipped next to this module in src and copied beside the bundle in
+// dist (tsup onSuccess); byte-identical to the Python append.lua.
+export const APPEND_LUA = readFileSync(new URL('./append.lua', import.meta.url), 'utf8');
+export const POLL_MS = 100;
+//# sourceMappingURL=constants.js.map

package/dist/shell/console/redis/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/shell/console/redis/constants.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC,mEAAmE;AACnE,qEAAqE;AACrE,qEAAqE;AACrE,qEAAqE;AACrE,kEAAkE;AAClE,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAA;AAExF,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAA"}

package/dist/shell/console/redis/index.d.ts

@@ -0,0 +1,2 @@
+export { RedisConsoleStore, type RedisConsoleStoreOptions } from './store.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/shell/console/redis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/shell/console/redis/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAA"}

package/dist/shell/console/redis/index.js

@@ -0,0 +1,15 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+export { RedisConsoleStore } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/shell/console/redis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/shell/console/redis/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,iBAAiB,EAAiC,MAAM,YAAY,CAAA"}

package/dist/shell/console/redis/store.d.ts

@@ -0,0 +1,67 @@
+import { Channel } from '@struktoai/mirage-core/shell/console/index';
+import type { ConsoleChunk, ConsoleStore, ReadResult } from '@struktoai/mirage-core/shell/console/index';
+export interface RedisConsoleStoreOptions {
+    url?: string;
+    keyPrefix?: string;
+    /** Expire the keys this long after the last append; absent keeps them. */
+    ttlSeconds?: number;
+}
+/**
+ * Console storage on a Redis stream, for readers in other processes.
+ *
+ * One stream per job: chunk seq maps to stream id `(seq+1)-0`, with the
+ * channel, payload and timestamp as entry fields (`c`/`d`/`t`). The
+ * job's process appends through its store instance; a reader anywhere
+ * else attaches its own instance on the same keyPrefix and follows
+ * live, which is what RAM cannot offer. The schema matches the Python
+ * RedisConsoleStore byte for byte, so the reader does not have to be
+ * the writer's language.
+ *
+ * The job owns its keys: a factory must hand every job a prefix nothing
+ * else has written, because a reused stream replays the previous job's
+ * chunks, ending chunk included. `keyPrefix` stays public because it is
+ * the console's address: an embedder reads it off a job's store and
+ * hands it to the process that should attach.
+ *
+ * The ending chunk is terminal in the store itself, not only in this
+ * process: the append script refuses any append once a CONTROL chunk
+ * landed, so an emit that raced a kill past `JobConsole`'s local guard
+ * is dropped server-side instead of landing after the ending.
+ *
+ * `wait` polls the seq counter rather than blocking server-side the way
+ * Python's XREAD BLOCK does: node-redis serializes commands on one
+ * connection, so a blocking read would wedge the job's own appends
+ * behind it, and a second connection costs more than a short poll.
+ * There is no retention trim, so readFrom never reports a truncated
+ * cursor; retention is bounded by `ttlSeconds` instead, refreshed on
+ * every append, so a console expires that long after its job's last
+ * write.
+ */
+export declare class RedisConsoleStore implements ConsoleStore {
+    readonly url: string;
+    readonly keyPrefix: string;
+    private readonly streamKey;
+    private readonly counterKey;
+    private readonly endedKey;
+    private readonly ttlSeconds;
+    private clientPromise;
+    private isClosed;
+    constructor(options?: RedisConsoleStoreOptions);
+    get closed(): boolean;
+    private client;
+    /**
+     * Append one chunk, atomically against the console's ending.
+     *
+     * A dropped append (the console already ended) reports the last real
+     * chunk's seq; `JobConsole.emit` ignores the return and the drop is
+     * exactly its documented after-the-ending semantics.
+     */
+    append(channel: Channel, data: Uint8Array): Promise<ConsoleChunk>;
+    readFrom(seq: number, limit?: number): Promise<ReadResult>;
+    wait(seq: number): Promise<void>;
+    close(): Promise<void>;
+    /** Delete the console's keys (test and integ teardown only). */
+    clear(): Promise<void>;
+    private chunk;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/shell/console/redis/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/shell/console/redis/store.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,OAAO,EAAE,MAAM,4CAA4C,CAAA;AACpE,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACX,MAAM,4CAA4C,CAAA;AASnD,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACpD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,OAAO,GAAE,wBAA6B;IASlD,IAAI,MAAM,IAAI,OAAO,CAEpB;YAEa,MAAM;IAmBpB;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAiBjE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAqC1D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,gEAAgE;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,OAAO,CAAC,KAAK;CAQd"}