@enbox/auth 0.3.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/dist/esm/auth-manager.js +245 -5
  2. package/dist/esm/auth-manager.js.map +1 -1
  3. package/dist/esm/flows/dwn-discovery.js +96 -81
  4. package/dist/esm/flows/dwn-discovery.js.map +1 -1
  5. package/dist/esm/flows/dwn-registration.js +49 -3
  6. package/dist/esm/flows/dwn-registration.js.map +1 -1
  7. package/dist/esm/flows/import-identity.js +2 -0
  8. package/dist/esm/flows/import-identity.js.map +1 -1
  9. package/dist/esm/flows/local-connect.js +25 -8
  10. package/dist/esm/flows/local-connect.js.map +1 -1
  11. package/dist/esm/flows/session-restore.js +20 -4
  12. package/dist/esm/flows/session-restore.js.map +1 -1
  13. package/dist/esm/flows/wallet-connect.js +5 -4
  14. package/dist/esm/flows/wallet-connect.js.map +1 -1
  15. package/dist/esm/index.js +5 -1
  16. package/dist/esm/index.js.map +1 -1
  17. package/dist/esm/password-provider.js +319 -0
  18. package/dist/esm/password-provider.js.map +1 -0
  19. package/dist/esm/types.js +9 -1
  20. package/dist/esm/types.js.map +1 -1
  21. package/dist/types/auth-manager.d.ts +83 -2
  22. package/dist/types/auth-manager.d.ts.map +1 -1
  23. package/dist/types/flows/dwn-discovery.d.ts +40 -53
  24. package/dist/types/flows/dwn-discovery.d.ts.map +1 -1
  25. package/dist/types/flows/dwn-registration.d.ts +20 -1
  26. package/dist/types/flows/dwn-registration.d.ts.map +1 -1
  27. package/dist/types/flows/import-identity.d.ts.map +1 -1
  28. package/dist/types/flows/local-connect.d.ts +2 -0
  29. package/dist/types/flows/local-connect.d.ts.map +1 -1
  30. package/dist/types/flows/session-restore.d.ts +2 -0
  31. package/dist/types/flows/session-restore.d.ts.map +1 -1
  32. package/dist/types/flows/wallet-connect.d.ts +2 -2
  33. package/dist/types/flows/wallet-connect.d.ts.map +1 -1
  34. package/dist/types/index.d.ts +5 -2
  35. package/dist/types/index.d.ts.map +1 -1
  36. package/dist/types/password-provider.d.ts +194 -0
  37. package/dist/types/password-provider.d.ts.map +1 -0
  38. package/dist/types/types.d.ts +106 -1
  39. package/dist/types/types.d.ts.map +1 -1
  40. package/package.json +8 -9
  41. package/src/auth-manager.ts +284 -9
  42. package/src/flows/dwn-discovery.ts +99 -79
  43. package/src/flows/dwn-registration.ts +60 -5
  44. package/src/flows/import-identity.ts +2 -0
  45. package/src/flows/local-connect.ts +24 -3
  46. package/src/flows/session-restore.ts +22 -2
  47. package/src/flows/wallet-connect.ts +5 -4
  48. package/src/index.ts +10 -1
  49. package/src/password-provider.ts +383 -0
  50. package/src/types.ts +114 -1
@@ -7,26 +7,21 @@
7
7
  *
8
8
  * ## Discovery channels (browser, highest to lowest priority)
9
9
  *
10
- * 1. **URL fragment payload** — A `dwn://register` redirect just landed
10
+ * 1. **URL fragment payload** — A `dwn://connect` redirect just landed
11
11
  * on the page with the endpoint in `#`. Highest priority because it's
12
12
  * fresh and explicit.
13
13
  * 2. **Persisted endpoint** (localStorage) — A previously discovered
14
14
  * endpoint restored and re-validated via `GET /info`.
15
- * 3. **Agent-level discovery** (transparent, runs on every `sendRequest`)
16
- * — `~/.enbox/dwn.json` discovery file (Node/Bun only; skipped in
17
- * browsers) and sequential port probing on `127.0.0.1:{3000,55500–55509}`.
18
- * This channel works even if the browser-specific functions here
19
- * return `false`.
20
15
  *
21
16
  * ## Discovery channels (CLI / native, all transparent)
22
17
  *
23
- * In Node/Bun environments, all discovery happens automatically inside
18
+ * In Node/Bun environments, the agent's `LocalDwnDiscovery` reads the
19
+ * `~/.enbox/dwn.json` discovery file automatically inside
24
20
  * `AgentDwnApi.getLocalDwnEndpoint()`. The browser-specific functions
25
21
  * in this module (`checkUrlForDwnDiscoveryPayload`, `requestLocalDwnDiscovery`)
26
- * are not needed the agent reads `~/.enbox/dwn.json` and probes ports
27
- * on its own.
22
+ * are not needed in those environments.
28
23
  *
29
- * @see https://github.com/enboxorg/enbox/issues/589
24
+ * @see https://github.com/enboxorg/enbox/issues/677
30
25
  * @module
31
26
  */
32
27
  import type { EnboxUserAgent } from '@enbox/agent';
@@ -36,7 +31,7 @@ import type { StorageAdapter } from '../types.js';
36
31
  * Check the current page URL for a `DwnDiscoveryPayload` in the fragment.
37
32
  *
38
33
  * This is called once at the start of a connection flow to detect whether
39
- * the user was just redirected back from a `dwn://register` handler. If a
34
+ * the user was just redirected back from a `dwn://connect` handler. If a
40
35
  * valid payload is found, the endpoint is persisted and the fragment is
41
36
  * cleared to prevent double-reads.
42
37
  *
@@ -44,6 +39,28 @@ import type { StorageAdapter } from '../types.js';
44
39
  * was found in the URL.
45
40
  */
46
41
  export declare function checkUrlForDwnDiscoveryPayload(): string | undefined;
42
+ /**
43
+ * Run local DWN discovery **before the agent exists**.
44
+ *
45
+ * This is the standalone counterpart of {@link applyLocalDwnDiscovery} and
46
+ * is designed to be called in `AuthManager.create()`, before
47
+ * `EnboxUserAgent.create()`, so the agent creation can decide whether to
48
+ * spin up an in-process DWN or operate in remote mode.
49
+ *
50
+ * Discovery channels (highest → lowest priority):
51
+ * 1. **URL fragment payload** — A `dwn://connect` redirect just landed.
52
+ * 2. **Persisted endpoint** (localStorage) — A previously discovered
53
+ * endpoint, re-validated via `GET /info`.
54
+ *
55
+ * When a valid endpoint is found it is persisted to storage. When a
56
+ * previously-persisted endpoint is stale, it is removed.
57
+ *
58
+ * @param storage - The auth storage adapter (for reading/writing the
59
+ * cached endpoint).
60
+ * @returns The validated endpoint URL, or `undefined` if no local DWN
61
+ * server is available.
62
+ */
63
+ export declare function discoverLocalDwn(storage: StorageAdapter): Promise<string | undefined>;
47
64
  /**
48
65
  * Persist a discovered local DWN endpoint in auth storage.
49
66
  *
@@ -76,25 +93,18 @@ export declare function restoreLocalDwnEndpoint(agent: EnboxUserAgent, storage:
76
93
  * Run the full local DWN discovery sequence for a browser connection flow.
77
94
  *
78
95
  * This function handles the **receiving** side of local DWN discovery in
79
- * the browser. It does NOT trigger the `dwn://register` redirect — use
96
+ * the browser. It does NOT trigger the `dwn://connect` redirect — use
80
97
  * {@link requestLocalDwnDiscovery} for that.
81
98
  *
82
99
  * The discovery channels, from highest to lowest priority:
83
100
  *
84
- * 1. **URL fragment payload** — A `dwn://register` redirect just landed on
101
+ * 1. **URL fragment payload** — A `dwn://connect` redirect just landed on
85
102
  * this page with the DWN endpoint in `#`. This is the highest-priority
86
103
  * signal because it's fresh and explicit.
87
104
  *
88
105
  * 2. **Persisted endpoint** (localStorage) — A previously discovered
89
106
  * endpoint is restored and re-validated via `GET /info`.
90
107
  *
91
- * 3. **Agent-level discovery** (transparent) — Even if this function
92
- * returns `false`, the agent's `LocalDwnDiscovery` will independently
93
- * try the discovery file (`~/.enbox/dwn.json`) and port probing on
94
- * every `sendRequest()` call. Those channels are not available in
95
- * browsers (no filesystem access, CORS may block probes), but they
96
- * work transparently in Node/Bun CLI environments.
97
- *
98
108
  * When an `emitter` is provided, this function emits:
99
109
  * - `'local-dwn-available'` with the endpoint when discovery succeeds.
100
110
  * - `'local-dwn-unavailable'` when no local DWN could be reached.
@@ -106,52 +116,29 @@ export declare function restoreLocalDwnEndpoint(agent: EnboxUserAgent, storage:
106
116
  */
107
117
  export declare function applyLocalDwnDiscovery(agent: EnboxUserAgent, storage: StorageAdapter, emitter?: AuthEventEmitter): Promise<boolean>;
108
118
  /**
109
- * Initiate the `dwn://register` flow by opening the register URL.
119
+ * Initiate the `dwn://connect` flow by opening the connect URL.
110
120
  *
111
- * This asks the operating system to route `dwn://register?callback=<url>`
121
+ * This asks the operating system to route `dwn://connect?callback=<url>`
112
122
  * to the registered handler (electrobun-dwn), which will redirect the
113
123
  * user's browser back to `callbackUrl` with the local DWN endpoint
114
124
  * encoded in the URL fragment.
115
125
  *
116
- * **Important:** There is no reliable cross-browser API to detect whether
117
- * a `dwn://` handler is installed. If no handler is registered, this call
118
- * will silently fail or show an OS-level error dialog. Use
119
- * {@link probeLocalDwn} first to check if a local DWN is already
120
- * reachable via port probing — if it is, you can skip the register flow
121
- * entirely and call {@link applyLocalDwnDiscovery} instead.
126
+ * **Note:** There is no reliable cross-browser API to detect whether a
127
+ * `dwn://` handler is installed. If no handler is registered, this call
128
+ * will silently fail or show an OS-level error dialog.
122
129
  *
123
130
  * @param callbackUrl - The URL to redirect back to. Defaults to the
124
131
  * current page URL (without its fragment) if running in a browser.
125
- * @returns `true` if the register URL was opened, `false` if no
132
+ * @returns `true` if the connect URL was opened, `false` if no
126
133
  * callback URL could be determined (e.g. no `globalThis.location`).
127
134
  *
128
135
  * @example
129
136
  * ```ts
130
- * // Check if local DWN is already available via direct probe.
131
- * const alreadyAvailable = await probeLocalDwn();
132
- * if (!alreadyAvailable) {
133
- * // No local DWN found trigger the dwn://register flow.
134
- * requestLocalDwnDiscovery();
135
- * // The page will reload with the endpoint in the URL fragment.
136
- * }
137
+ * // Trigger the dwn://connect flow to discover a local DWN.
138
+ * requestLocalDwnDiscovery();
139
+ * // The page will reload with the endpoint in the URL fragment.
140
+ * // On the next connect/restore, applyLocalDwnDiscovery() reads it.
137
141
  * ```
138
142
  */
139
143
  export declare function requestLocalDwnDiscovery(callbackUrl?: string): boolean;
140
- /**
141
- * Probe whether a local DWN server is reachable via direct HTTP fetch.
142
- *
143
- * Attempts `GET http://127.0.0.1:{port}/info` on the well-known port
144
- * candidates and returns the endpoint URL of the first server that
145
- * responds with a valid `@enbox/dwn-server` identity.
146
- *
147
- * This is useful in browsers to check if a local DWN is available
148
- * *before* triggering the `dwn://register` redirect flow — if the
149
- * server is already reachable (CORS permitting), the redirect is
150
- * unnecessary.
151
- *
152
- * @returns The local DWN endpoint URL, or `undefined` if no server
153
- * was found. Returns `undefined` (rather than throwing) on CORS
154
- * errors or network failures.
155
- */
156
- export declare function probeLocalDwn(): Promise<string | undefined>;
157
144
  //# sourceMappingURL=dwn-discovery.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"dwn-discovery.d.ts","sourceRoot":"","sources":["../../../src/flows/dwn-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,GAAG,SAAS,CAkBnE;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAuBtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsBjE"}
1
+ {"version":3,"file":"dwn-discovery.d.ts","sourceRoot":"","sources":["../../../src/flows/dwn-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,GAAG,SAAS,CAkBnE;AA4BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwB7B;AAID;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAuBtE"}
@@ -11,7 +11,7 @@
11
11
  * @module
12
12
  */
13
13
  import type { EnboxUserAgent } from '@enbox/agent';
14
- import type { RegistrationOptions } from '../types.js';
14
+ import type { RegistrationOptions, RegistrationTokenData, StorageAdapter } from '../types.js';
15
15
  /** @internal */
16
16
  export interface RegistrationContext {
17
17
  /** The user agent with RPC access for getServerInfo(). */
@@ -22,6 +22,11 @@ export interface RegistrationContext {
22
22
  agentDid: string;
23
23
  /** The connected DID URI (the identity's DID). */
24
24
  connectedDid: string;
25
+ /**
26
+ * Storage adapter for automatic token persistence.
27
+ * Only used when `registration.persistTokens` is `true`.
28
+ */
29
+ storage?: StorageAdapter;
25
30
  }
26
31
  /**
27
32
  * Register the agent and connected DIDs with the configured DWN endpoints.
@@ -36,4 +41,18 @@ export interface RegistrationContext {
36
41
  * @internal
37
42
  */
38
43
  export declare function registerWithDwnEndpoints(ctx: RegistrationContext, registration: RegistrationOptions): Promise<void>;
44
+ /**
45
+ * Load registration tokens from a `StorageAdapter`.
46
+ *
47
+ * Returns an empty record if no tokens are stored or the stored value
48
+ * is corrupt (best-effort — never throws).
49
+ *
50
+ * @internal
51
+ */
52
+ export declare function loadTokensFromStorage(storage: StorageAdapter): Promise<Record<string, RegistrationTokenData>>;
53
+ /**
54
+ * Save registration tokens to a `StorageAdapter`.
55
+ * @internal
56
+ */
57
+ export declare function saveTokensToStorage(storage: StorageAdapter, tokens: Record<string, RegistrationTokenData>): Promise<void>;
39
58
  //# sourceMappingURL=dwn-registration.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"dwn-registration.d.ts","sourceRoot":"","sources":["../../../src/flows/dwn-registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,KAAK,EACV,mBAAmB,EAEpB,MAAM,aAAa,CAAC;AAErB,gBAAgB;AAChB,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,SAAS,EAAE,cAAc,CAAC;IAE1B,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IAEjB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,mBAAmB,EACxB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,IAAI,CAAC,CAwGf"}
1
+ {"version":3,"file":"dwn-registration.d.ts","sourceRoot":"","sources":["../../../src/flows/dwn-registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,gBAAgB;AAChB,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,SAAS,EAAE,cAAc,CAAC;IAE1B,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IAEjB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,mBAAmB,EACxB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,IAAI,CAAC,CAqHf;AAID;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAQhD;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAEf"}
@@ -1 +1 @@
1
- {"version":3,"file":"import-identity.d.ts","sourceRoot":"","sources":["../../../src/flows/import-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,KAAK,EACV,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,gBAAgB;AAChB,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAuGtB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CA6DtB"}
1
+ {"version":3,"file":"import-identity.d.ts","sourceRoot":"","sources":["../../../src/flows/import-identity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,KAAK,EACV,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,gBAAgB;AAChB,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAwGtB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CA8DtB"}
@@ -7,6 +7,7 @@
7
7
  */
8
8
  import type { EnboxUserAgent } from '@enbox/agent';
9
9
  import type { AuthEventEmitter } from '../events.js';
10
+ import type { PasswordProvider } from '../password-provider.js';
10
11
  import type { LocalConnectOptions, RegistrationOptions, StorageAdapter, SyncOption } from '../types.js';
11
12
  import { AuthSession } from '../identity-session.js';
12
13
  /** @internal */
@@ -15,6 +16,7 @@ export interface LocalConnectContext {
15
16
  emitter: AuthEventEmitter;
16
17
  storage: StorageAdapter;
17
18
  defaultPassword?: string;
19
+ passwordProvider?: PasswordProvider;
18
20
  defaultSync?: SyncOption;
19
21
  defaultDwnEndpoints?: string[];
20
22
  registration?: RegistrationOptions;
@@ -1 +1 @@
1
- {"version":3,"file":"local-connect.d.ts","sourceRoot":"","sources":["../../../src/flows/local-connect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGxG,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAIrD,gBAAgB;AAChB,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,mBAAmB,EACxB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,WAAW,CAAC,CAoItB"}
1
+ {"version":3,"file":"local-connect.d.ts","sourceRoot":"","sources":["../../../src/flows/local-connect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGxG,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAIrD,gBAAgB;AAChB,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,mBAAmB,EACxB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,WAAW,CAAC,CAuJtB"}
@@ -7,6 +7,7 @@
7
7
  */
8
8
  import type { EnboxUserAgent } from '@enbox/agent';
9
9
  import type { AuthEventEmitter } from '../events.js';
10
+ import type { PasswordProvider } from '../password-provider.js';
10
11
  import type { RestoreSessionOptions, StorageAdapter, SyncOption } from '../types.js';
11
12
  import { AuthSession } from '../identity-session.js';
12
13
  /** @internal */
@@ -15,6 +16,7 @@ export interface SessionRestoreContext {
15
16
  emitter: AuthEventEmitter;
16
17
  storage: StorageAdapter;
17
18
  defaultPassword?: string;
19
+ passwordProvider?: PasswordProvider;
18
20
  defaultSync?: SyncOption;
19
21
  }
20
22
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"session-restore.d.ts","sourceRoot":"","sources":["../../../src/flows/session-restore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,gBAAgB;AAChB,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,qBAAqB,EAC1B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAmGlC"}
1
+ {"version":3,"file":"session-restore.d.ts","sourceRoot":"","sources":["../../../src/flows/session-restore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrF,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,gBAAgB;AAChB,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,qBAAqB,EAC1B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAqHlC"}
@@ -1,7 +1,7 @@
1
1
  /**
2
- * Wallet connect (OIDC/QR) flow.
2
+ * Wallet connect (Enbox Connect relay) flow.
3
3
  *
4
- * Connects to an external wallet via the WalletConnect relay protocol,
4
+ * Connects to an external wallet via the Enbox Connect relay protocol,
5
5
  * importing a delegated DID with permission grants.
6
6
  * This replaces the "Mode B/C" paths in Enbox.connect().
7
7
  * @module
@@ -1 +1 @@
1
- {"version":3,"file":"wallet-connect.d.ts","sourceRoot":"","sources":["../../../src/flows/wallet-connect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,iCAAiC,EAAyD,cAAc,EAAE,MAAM,cAAc,CAAC;AAG7I,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEzG,gBAAgB;AAChB,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,iCAAiC,EAAE,CAAC;CAC7C,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmCpB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAsItB"}
1
+ {"version":3,"file":"wallet-connect.d.ts","sourceRoot":"","sources":["../../../src/flows/wallet-connect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,iCAAiC,EAAyD,cAAc,EAAE,MAAM,cAAc,CAAC;AAG7I,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEzG,gBAAgB;AAChB,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,iCAAiC,EAAE,CAAC;CAC7C,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmCpB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAuItB"}
@@ -37,9 +37,12 @@ export { AuthManager } from './auth-manager.js';
37
37
  export { AuthSession } from './identity-session.js';
38
38
  export { VaultManager } from './vault/vault-manager.js';
39
39
  export { AuthEventEmitter } from './events.js';
40
+ export { PasswordProvider } from './password-provider.js';
41
+ export type { PasswordContext } from './password-provider.js';
40
42
  export { EnboxUserAgent, HdIdentityVault } from '@enbox/agent';
41
43
  export { processConnectedGrants } from './flows/wallet-connect.js';
42
- export { applyLocalDwnDiscovery, checkUrlForDwnDiscoveryPayload, clearLocalDwnEndpoint, persistLocalDwnEndpoint, probeLocalDwn, requestLocalDwnDiscovery, restoreLocalDwnEndpoint, } from './flows/dwn-discovery.js';
44
+ export { loadTokensFromStorage, saveTokensToStorage } from './flows/dwn-registration.js';
45
+ export { applyLocalDwnDiscovery, checkUrlForDwnDiscoveryPayload, clearLocalDwnEndpoint, discoverLocalDwn, persistLocalDwnEndpoint, requestLocalDwnDiscovery, restoreLocalDwnEndpoint, } from './flows/dwn-discovery.js';
43
46
  export { BrowserStorage, LevelStorage, MemoryStorage, createDefaultStorage } from './storage/storage.js';
44
- export type { AuthEvent, AuthEventHandler, AuthEventMap, AuthManagerOptions, AuthSessionInfo, AuthState, ConnectPermissionRequest, DisconnectOptions, IdentityInfo, IdentityVaultBackup, ImportFromPhraseOptions, ImportFromPortableOptions, LocalConnectOptions, LocalDwnStrategy, PortableIdentity, ProviderAuthParams, ProviderAuthResult, RegistrationOptions, RegistrationTokenData, RestoreSessionOptions, StorageAdapter, SyncOption, WalletConnectOptions, } from './types.js';
47
+ export type { AuthEvent, AuthEventHandler, AuthEventMap, AuthManagerOptions, AuthSessionInfo, AuthState, ConnectPermissionRequest, DisconnectOptions, HeadlessConnectOptions, IdentityInfo, IdentityVaultBackup, ImportFromPhraseOptions, ImportFromPortableOptions, LocalConnectOptions, LocalDwnStrategy, PortableIdentity, ProviderAuthParams, ProviderAuthResult, RegistrationOptions, RegistrationTokenData, RestoreSessionOptions, ShutdownOptions, StorageAdapter, SyncOption, WalletConnectOptions, } from './types.js';
45
48
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/C,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,OAAO,EACL,sBAAsB,EACtB,8BAA8B,EAC9B,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGzG,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,wBAAwB,EACxB,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,oBAAoB,GACrB,MAAM,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGzF,OAAO,EACL,sBAAsB,EACtB,8BAA8B,EAC9B,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGzG,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,UAAU,EACV,oBAAoB,GACrB,MAAM,YAAY,CAAC"}
@@ -0,0 +1,194 @@
1
+ /**
2
+ * PasswordProvider — composable password acquisition strategies.
3
+ *
4
+ * Replaces ad-hoc password prompting scattered across CLI consumers
5
+ * (env vars, raw-mode TTY, `/dev/tty` + `stty`, `@clack/prompts`, etc.)
6
+ * with a single, composable abstraction.
7
+ *
8
+ * @example Chained provider (env first, fall back to TTY)
9
+ * ```ts
10
+ * import { PasswordProvider } from '@enbox/auth';
11
+ *
12
+ * const provider = PasswordProvider.chain([
13
+ * PasswordProvider.fromEnv('ENBOX_PASSWORD'),
14
+ * PasswordProvider.fromTty({ prompt: 'Vault password: ' }),
15
+ * ]);
16
+ *
17
+ * const auth = await AuthManager.create({ passwordProvider: provider });
18
+ * ```
19
+ *
20
+ * @module
21
+ */
22
+ /** Context passed to a password provider explaining why a password is needed. */
23
+ export interface PasswordContext {
24
+ /**
25
+ * Why the password is being requested.
26
+ *
27
+ * - `'create'` — first launch, creating a new vault (prompt may ask
28
+ * for confirmation).
29
+ * - `'unlock'` — unlocking an existing vault.
30
+ */
31
+ reason: 'create' | 'unlock';
32
+ }
33
+ /**
34
+ * A strategy for obtaining a vault password.
35
+ *
36
+ * Implementations may be interactive (TTY prompts) or non-interactive
37
+ * (environment variables, cached values). Use {@link PasswordProvider.chain}
38
+ * to compose multiple strategies with automatic fallback.
39
+ */
40
+ export interface PasswordProvider {
41
+ /**
42
+ * Obtain a password.
43
+ *
44
+ * @param context - Why the password is needed.
45
+ * @returns The password string.
46
+ * @throws If the provider cannot obtain a password (e.g. env var
47
+ * not set, no TTY available). The error is caught by `chain()`
48
+ * which falls through to the next provider.
49
+ */
50
+ getPassword(context: PasswordContext): Promise<string>;
51
+ }
52
+ /** @internal Minimal interface for an stdin-like readable stream. */
53
+ export interface TtyReadable {
54
+ isTTY?: boolean;
55
+ setRawMode(mode: boolean): void;
56
+ setEncoding(encoding: string): void;
57
+ resume(): void;
58
+ pause(): void;
59
+ on(event: 'data', listener: (chunk: string) => void): void;
60
+ removeListener(event: 'data', listener: (chunk: string) => void): void;
61
+ }
62
+ /** @internal Minimal interface for an stdout-like writable stream. */
63
+ export interface TtyWritable {
64
+ write(data: string): boolean;
65
+ }
66
+ /**
67
+ * Read a password from a raw-mode TTY stream.
68
+ *
69
+ * Reads character-by-character with no echo. Handles Enter (resolve),
70
+ * Ctrl-C (reject), backspace, and printable characters.
71
+ *
72
+ * @internal Exported for testing only.
73
+ */
74
+ export declare function readPasswordRawMode(stdin: TtyReadable, stdout: TtyWritable, prompt: string): Promise<string>;
75
+ /** @internal Injectable I/O for testing `readPasswordDevTty`. */
76
+ export interface DevTtyIo {
77
+ openSync(path: string, flags: string): number;
78
+ readSync(fd: number, buf: Uint8Array, offset: number, length: number, position: null): number;
79
+ writeSync(fd: number, data: string): number;
80
+ closeSync(fd: number): void;
81
+ execSync(cmd: string, opts: {
82
+ stdio: string;
83
+ }): void;
84
+ }
85
+ /**
86
+ * Read a password from `/dev/tty` using synchronous I/O.
87
+ *
88
+ * Opens `/dev/tty` directly, uses `stty -echo` to suppress input,
89
+ * reads until newline, then restores echo and closes file descriptors.
90
+ *
91
+ * @param prompt - The prompt string to display.
92
+ * @param io - Injectable I/O functions (defaults to `node:fs` + `node:child_process`).
93
+ * @internal Exported for testing only.
94
+ */
95
+ export declare function readPasswordDevTty(prompt: string, io?: DevTtyIo): Promise<string>;
96
+ export declare namespace PasswordProvider {
97
+ /**
98
+ * Read the password from an environment variable.
99
+ *
100
+ * Throws if the variable is not set or is empty, allowing `chain()`
101
+ * to fall through to the next provider.
102
+ *
103
+ * @param envVar - Name of the environment variable. Default: `'ENBOX_PASSWORD'`.
104
+ *
105
+ * @example
106
+ * ```ts
107
+ * const provider = PasswordProvider.fromEnv('MY_APP_PASSWORD');
108
+ * ```
109
+ */
110
+ function fromEnv(envVar?: string): PasswordProvider;
111
+ /**
112
+ * Wrap an async callback as a password provider.
113
+ *
114
+ * This is the escape hatch for custom UI (e.g. `@clack/prompts`,
115
+ * Electron dialog, browser modal).
116
+ *
117
+ * @param callback - Called with the password context; must return a password string.
118
+ *
119
+ * @example
120
+ * ```ts
121
+ * const provider = PasswordProvider.fromCallback(async ({ reason }) => {
122
+ * if (reason === 'create') {
123
+ * return await showCreatePasswordDialog();
124
+ * }
125
+ * return await showUnlockDialog();
126
+ * });
127
+ * ```
128
+ */
129
+ function fromCallback(callback: (context: PasswordContext) => Promise<string>): PasswordProvider;
130
+ /**
131
+ * Prompt for a password via `process.stdin` in raw mode.
132
+ *
133
+ * Input is read character-by-character with no echo. Handles
134
+ * backspace and Ctrl-C (rejects with an error). Only works when
135
+ * `process.stdin.isTTY` is `true`; throws otherwise so `chain()`
136
+ * can fall through to the next provider.
137
+ *
138
+ * Suitable for main CLI processes that own stdin/stdout.
139
+ *
140
+ * @param options - Optional configuration.
141
+ * @param options.prompt - Text to display before reading. Default: `'Vault password: '`.
142
+ *
143
+ * @example
144
+ * ```ts
145
+ * const provider = PasswordProvider.fromTty({ prompt: 'Password: ' });
146
+ * ```
147
+ */
148
+ function fromTty(options?: {
149
+ prompt?: string;
150
+ }): PasswordProvider;
151
+ /**
152
+ * Prompt for a password via `/dev/tty` (Unix only).
153
+ *
154
+ * Opens `/dev/tty` directly, bypassing `process.stdin`. This is
155
+ * essential for subprocesses where stdin is owned by the parent
156
+ * (e.g. Git credential helpers, SSH, GPG). Uses `stty -echo` to
157
+ * suppress input echo.
158
+ *
159
+ * Throws if `/dev/tty` cannot be opened (e.g. non-Unix platform,
160
+ * no controlling terminal), allowing `chain()` to fall through.
161
+ *
162
+ * @param options - Optional configuration.
163
+ * @param options.prompt - Text to display before reading. Default: `'Vault password: '`.
164
+ *
165
+ * @example
166
+ * ```ts
167
+ * // For git credential helpers:
168
+ * const provider = PasswordProvider.fromDevTty();
169
+ * ```
170
+ */
171
+ function fromDevTty(options?: {
172
+ prompt?: string;
173
+ }): PasswordProvider;
174
+ /**
175
+ * Compose multiple providers with automatic fallback.
176
+ *
177
+ * Tries each provider in order. If a provider throws, the next one
178
+ * is tried. If all providers fail, the last error is rethrown.
179
+ *
180
+ * @param providers - Ordered list of providers to try.
181
+ *
182
+ * @example
183
+ * ```ts
184
+ * // Try env var first, then interactive TTY, then /dev/tty for subprocesses.
185
+ * const provider = PasswordProvider.chain([
186
+ * PasswordProvider.fromEnv('ENBOX_PASSWORD'),
187
+ * PasswordProvider.fromTty(),
188
+ * PasswordProvider.fromDevTty(),
189
+ * ]);
190
+ * ```
191
+ */
192
+ function chain(providers: PasswordProvider[]): PasswordProvider;
193
+ }
194
+ //# sourceMappingURL=password-provider.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"password-provider.d.ts","sourceRoot":"","sources":["../../src/password-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxD;AAID,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;IACd,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3D,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;CACxE;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAuCjB;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,MAAM,CAAC;IAC9F,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACtD;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,EAAE,CAAC,EAAE,QAAQ,GACZ,OAAO,CAAC,MAAM,CAAC,CAkEjB;AAKD,yBAAiB,gBAAgB,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,SAAgB,OAAO,CAAC,MAAM,SAAmB,GAAG,gBAAgB,CAYnE;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAgB,YAAY,CAC1B,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,GACtD,gBAAgB,CAElB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAgB,OAAO,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,gBAAgB,CAkB3E;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAgB,UAAU,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,gBAAgB,CAQ9E;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAgB,KAAK,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,CAoBrE;CACF"}