@dnsid-ai/sdk 0.20.1
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.
- package/LICENSE +201 -0
- package/README.md +121 -0
- package/dist/index.cjs +657 -0
- package/dist/index.d.cts +210 -0
- package/dist/index.d.ts +210 -0
- package/dist/index.js +625 -0
- package/dist/node.cjs +560 -0
- package/dist/node.d.cts +195 -0
- package/dist/node.d.ts +195 -0
- package/dist/node.js +518 -0
- package/package.json +61 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
import { VerificationError, KeyProvider, DnsIdJWK, IdentityManagerDependencies, DnsidConfig, IdentityManager } from '@dnsid-ai/protocol';
|
|
2
|
+
export * from '@dnsid-ai/protocol';
|
|
3
|
+
export { ArgumentError, DNSID_VERSION, DNSSECMode, DNSSECState, DnsIdTxtRecord, DomainLog, DomainSnapshot, IdentityManager, InMemoryIdentityCache, JWKS, JWKS_MAX_RESPONSE_BYTES, LogRegistry, NoopLogReader, ParseError, SIGNING_ALGS, STATUS_MAX_RESPONSE_BYTES, ValidationError, VerificationCode, VerificationError, VerifiedDomain, activeStatusDocument, fromBase64Url, isDomainName, isTransientVerificationError, jwkSignatureAlg, jwkThumbprint, normalizeFQDN, parseKaDuration, parseKeyId, retryTransientVerification, toArrayBuffer, toBase64Url, validateAgentStatus, verifyWithKey } from '@dnsid-ai/protocol';
|
|
4
|
+
import * as jose from '@dnsid-ai/jose';
|
|
5
|
+
export { jose };
|
|
6
|
+
export { JoseProfile, createJoseProfile } from '@dnsid-ai/jose';
|
|
7
|
+
import * as httpSignatures from '@dnsid-ai/http-signatures';
|
|
8
|
+
export { httpSignatures };
|
|
9
|
+
export { HttpSignaturesProfile, createHttpSignaturesProfile } from '@dnsid-ai/http-signatures';
|
|
10
|
+
import { SubmissionResult, KeyRotationPreparationRequest, PreparedRegistryEvent } from '@dnsid-ai/registry';
|
|
11
|
+
import * as registry from '@dnsid-ai/registry';
|
|
12
|
+
export { registry };
|
|
13
|
+
export { DEFAULT_REGISTRY_URL, PreparedEventSubmissionError, RegistryClient, RegistryWorkflowError, awaitRegistryManagedPublication, publishClientControlledRecord, publishToRegistry } from '@dnsid-ai/registry';
|
|
14
|
+
import * as webBotAuth from '@dnsid-ai/web-bot-auth';
|
|
15
|
+
export { webBotAuth };
|
|
16
|
+
export { WebBotAuthProfile, createWebBotAuthProfile } from '@dnsid-ai/web-bot-auth';
|
|
17
|
+
|
|
18
|
+
interface ManagedKeyRotationRegistry {
|
|
19
|
+
prepareKeyRotation(domain: string, request: KeyRotationPreparationRequest, idempotencyKey: string): Promise<PreparedRegistryEvent>;
|
|
20
|
+
submitPreparedEvent(domain: string, entryBytes: Uint8Array, idempotencyKey: string): Promise<SubmissionResult>;
|
|
21
|
+
}
|
|
22
|
+
interface RotateManagedOperationalKeyOptions {
|
|
23
|
+
domain: string;
|
|
24
|
+
/** Exact unindexed c2sp-tlog reference configured for this identity. */
|
|
25
|
+
logReference: string;
|
|
26
|
+
keyProvider: KeyProvider;
|
|
27
|
+
registryClient: ManagedKeyRotationRegistry;
|
|
28
|
+
idempotencyKey: string;
|
|
29
|
+
/** Durably persists exact bytes and every subsequent reconciliation state. */
|
|
30
|
+
persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
|
|
31
|
+
/** Pauses application signing before submission and resumes it only after durable activation. */
|
|
32
|
+
setApplicationSigningPaused: (paused: boolean) => Promise<void>;
|
|
33
|
+
}
|
|
34
|
+
interface ManagedKeyRotationResult {
|
|
35
|
+
readonly domain: string;
|
|
36
|
+
readonly logReference: string;
|
|
37
|
+
readonly previousKid: string;
|
|
38
|
+
readonly newKid: string;
|
|
39
|
+
/**
|
|
40
|
+
* Persist these exact bytes with idempotencyKey while activated is false.
|
|
41
|
+
* Callers must pause new application signing until this rotation is accepted.
|
|
42
|
+
*/
|
|
43
|
+
readonly entryBytes: Uint8Array;
|
|
44
|
+
readonly idempotencyKey: string;
|
|
45
|
+
readonly submission?: SubmissionResult;
|
|
46
|
+
readonly activated: boolean;
|
|
47
|
+
readonly applicationSigningPaused: boolean;
|
|
48
|
+
}
|
|
49
|
+
interface ResumeManagedOperationalKeyRotationOptions {
|
|
50
|
+
keyProvider: KeyProvider;
|
|
51
|
+
registryClient: Pick<ManagedKeyRotationRegistry, 'submitPreparedEvent'>;
|
|
52
|
+
rotation: ManagedKeyRotationResult;
|
|
53
|
+
persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
|
|
54
|
+
setApplicationSigningPaused: (paused: boolean) => Promise<void>;
|
|
55
|
+
}
|
|
56
|
+
/** Submission failed after the completed entry bytes were fixed. */
|
|
57
|
+
declare class ManagedKeyRotationSubmissionError extends VerificationError {
|
|
58
|
+
readonly rotation: ManagedKeyRotationResult;
|
|
59
|
+
readonly retryWithSameBytes: boolean;
|
|
60
|
+
constructor(message: string, rotation: ManagedKeyRotationResult, retryWithSameBytes: boolean, cause?: unknown);
|
|
61
|
+
}
|
|
62
|
+
/** Registry acceptance succeeded, but local key-state reconciliation did not. */
|
|
63
|
+
declare class ManagedKeyRotationActivationError extends VerificationError {
|
|
64
|
+
readonly rotation: ManagedKeyRotationResult;
|
|
65
|
+
constructor(message: string, rotation: ManagedKeyRotationResult, cause?: unknown);
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Runs C2SP registry-managed rotation. The registry owns managed ku publication
|
|
69
|
+
* and append reconciliation; local activation happens only after an accepted
|
|
70
|
+
* result for the exact, durably persisted bytes while application signing is paused.
|
|
71
|
+
*/
|
|
72
|
+
declare function rotateManagedOperationalKey(options: RotateManagedOperationalKeyOptions): Promise<ManagedKeyRotationResult>;
|
|
73
|
+
/** Retries only the persisted completed bytes and activates on acceptance. */
|
|
74
|
+
declare function resumeManagedOperationalKeyRotation(options: ResumeManagedOperationalKeyRotationOptions): Promise<ManagedKeyRotationResult>;
|
|
75
|
+
|
|
76
|
+
interface ManagedIssuanceRegistry {
|
|
77
|
+
prepareIssuance(domain: string, idempotencyKey: string): Promise<PreparedRegistryEvent>;
|
|
78
|
+
submitPreparedEvent(domain: string, entryBytes: Uint8Array, idempotencyKey: string): Promise<SubmissionResult>;
|
|
79
|
+
}
|
|
80
|
+
interface ManagedIssuanceState {
|
|
81
|
+
readonly domain: string;
|
|
82
|
+
readonly governanceId: string;
|
|
83
|
+
readonly idempotencyKey: string;
|
|
84
|
+
readonly entityKid: string;
|
|
85
|
+
readonly entityThumbprint: string;
|
|
86
|
+
readonly operationalKid: string;
|
|
87
|
+
readonly operationalThumbprint: string;
|
|
88
|
+
/** Undefined only while the durable intent precedes remote preparation. */
|
|
89
|
+
readonly logReference?: string;
|
|
90
|
+
/** Exact completed canonical bytes. Undefined only for an intent. */
|
|
91
|
+
readonly entryBytes?: Uint8Array;
|
|
92
|
+
/** SHA-256 of entryBytes, persisted before the first submission. */
|
|
93
|
+
readonly entryHash?: string;
|
|
94
|
+
readonly submission?: ManagedIssuanceSubmission;
|
|
95
|
+
readonly terminalFailure?: {
|
|
96
|
+
readonly stage: 'preparation' | 'submission';
|
|
97
|
+
readonly errorCode?: string;
|
|
98
|
+
};
|
|
99
|
+
readonly activated: boolean;
|
|
100
|
+
}
|
|
101
|
+
type ManagedIssuanceSubmission = SubmissionResult | {
|
|
102
|
+
readonly state: 'indeterminate';
|
|
103
|
+
readonly entryHash: string;
|
|
104
|
+
readonly errorCode?: string;
|
|
105
|
+
};
|
|
106
|
+
interface ManagedIssuanceCoordination {
|
|
107
|
+
/** Loads the one durable setup operation, if it exists. */
|
|
108
|
+
loadIssuance: () => Promise<ManagedIssuanceState | undefined>;
|
|
109
|
+
/** Atomically creates the intent; returns the existing operation if the create lost a race. */
|
|
110
|
+
createIssuance: (intent: ManagedIssuanceState) => Promise<ManagedIssuanceState | undefined>;
|
|
111
|
+
/** Atomically persists the intent, exact bytes, and every reconciliation transition. */
|
|
112
|
+
persistIssuance: (issuance: ManagedIssuanceState) => Promise<void>;
|
|
113
|
+
/**
|
|
114
|
+
* Publishes/converges status only after exact-byte log acceptance is durably bound.
|
|
115
|
+
* Must be idempotent because a crash can replay it before `activated` is persisted.
|
|
116
|
+
*/
|
|
117
|
+
activateAcceptedIssuance: (issuance: ManagedIssuanceState) => Promise<void>;
|
|
118
|
+
}
|
|
119
|
+
interface IssueManagedIdentityOptions extends ManagedIssuanceCoordination {
|
|
120
|
+
domain: string;
|
|
121
|
+
governanceId: string;
|
|
122
|
+
/** Trusted accountable-entity public key whose existing `sigs.ae` is required. */
|
|
123
|
+
entityKey: DnsIdJWK;
|
|
124
|
+
operationalKeyProvider: KeyProvider;
|
|
125
|
+
registryClient: ManagedIssuanceRegistry;
|
|
126
|
+
idempotencyKey: string;
|
|
127
|
+
/** Optional configured reference; a registry response must match it exactly. */
|
|
128
|
+
logReference?: string;
|
|
129
|
+
}
|
|
130
|
+
interface ResumeManagedIssuanceOptions extends ManagedIssuanceCoordination {
|
|
131
|
+
entityKey: DnsIdJWK;
|
|
132
|
+
operationalKeyProvider: KeyProvider;
|
|
133
|
+
registryClient: ManagedIssuanceRegistry;
|
|
134
|
+
}
|
|
135
|
+
declare class ManagedIssuanceSubmissionError extends VerificationError {
|
|
136
|
+
readonly issuance: ManagedIssuanceState;
|
|
137
|
+
readonly retryWithSameBytes: boolean;
|
|
138
|
+
constructor(message: string, issuance: ManagedIssuanceState, retryWithSameBytes: boolean, transient: boolean, cause?: unknown);
|
|
139
|
+
}
|
|
140
|
+
declare class ManagedIssuanceActivationError extends VerificationError {
|
|
141
|
+
readonly issuance: ManagedIssuanceState;
|
|
142
|
+
constructor(issuance: ManagedIssuanceState, cause: unknown);
|
|
143
|
+
}
|
|
144
|
+
/** Starts one durable managed setup operation, or resumes the already persisted one. */
|
|
145
|
+
declare function issueManagedIdentity(options: IssueManagedIdentityOptions): Promise<ManagedIssuanceState>;
|
|
146
|
+
/** Resumes only the durable operation, reusing its preparation key or exact completed bytes. */
|
|
147
|
+
declare function resumeManagedIssuance(options: ResumeManagedIssuanceOptions): Promise<ManagedIssuanceState>;
|
|
148
|
+
|
|
149
|
+
/** Immutable protocol-facing conformance metadata for this SDK release. */
|
|
150
|
+
interface SDKConformance {
|
|
151
|
+
readonly publishProfile: string;
|
|
152
|
+
readonly verificationProfiles: Readonly<Record<string, string>>;
|
|
153
|
+
readonly specificationStatus: 'internet-draft' | 'rfc';
|
|
154
|
+
readonly logBindings: Readonly<Record<string, string>>;
|
|
155
|
+
readonly knownDeviations: readonly string[];
|
|
156
|
+
}
|
|
157
|
+
/** Exact DNSid profile and log-binding behavior implemented by this SDK release. */
|
|
158
|
+
declare const SDK_CONFORMANCE: SDKConformance;
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Runtime-neutral SDK entry point for DNSid.
|
|
162
|
+
*
|
|
163
|
+
* `@dnsid-ai/sdk` aggregates the DNSid TypeScript packages: it re-exports
|
|
164
|
+
* the full protocol core (`@dnsid-ai/protocol`), the registry client and
|
|
165
|
+
* publishing helpers, the JOSE, HTTP message signatures, and web bot auth
|
|
166
|
+
* profiles, and managed operational key rotation workflows.
|
|
167
|
+
*
|
|
168
|
+
* This root entry point makes no runtime assumptions: callers inject DNS resolution,
|
|
169
|
+
* JSON fetching, key-provider, cache, and log implementations (see
|
|
170
|
+
* {@link createIdentityManager}). Node conveniences — LocalKeyProvider, environment
|
|
171
|
+
* config loading, and Node identity manager factories — live behind the
|
|
172
|
+
* `@dnsid-ai/sdk/node` subpath. OIDC support deliberately lives in
|
|
173
|
+
* `@dnsid-ai/oidc` (Node-bound transport) and is not re-exported here.
|
|
174
|
+
*
|
|
175
|
+
* @packageDocumentation
|
|
176
|
+
*/
|
|
177
|
+
|
|
178
|
+
/** Runtime-neutral dependencies: DNS and JSON fetching must be injected. */
|
|
179
|
+
type CreateIdentityManagerDependencies = IdentityManagerDependencies & Required<Pick<IdentityManagerDependencies, 'dnsResolver' | 'fetchJson'>>;
|
|
180
|
+
/**
|
|
181
|
+
* Creates a DNSid IdentityManager from explicitly injected runtime dependencies.
|
|
182
|
+
*
|
|
183
|
+
* The root `@dnsid-ai/sdk` entrypoint is runtime-neutral: callers provide DNS, HTTPS/JSON
|
|
184
|
+
* fetching, key storage/signing, cache, and log implementations appropriate for Node,
|
|
185
|
+
* browsers, workers, wallets, HSMs, or application backends. Omit `config.identity` for a
|
|
186
|
+
* verification-only manager (see {@link createIdentityVerifier}).
|
|
187
|
+
*
|
|
188
|
+
* @example
|
|
189
|
+
* ```ts
|
|
190
|
+
* import { createIdentityManager } from '@dnsid-ai/sdk';
|
|
191
|
+
*
|
|
192
|
+
* const idm = createIdentityManager({ identity, verification }, {
|
|
193
|
+
* keyProvider, // operational key
|
|
194
|
+
* entityKeyProvider, // entity key
|
|
195
|
+
* dnsResolver, // DNSSEC-aware resolver
|
|
196
|
+
* fetchJson,
|
|
197
|
+
* });
|
|
198
|
+
* const verified = await idm.verifyDomain('agent.example.com');
|
|
199
|
+
* ```
|
|
200
|
+
*/
|
|
201
|
+
declare function createIdentityManager(config: DnsidConfig, deps: CreateIdentityManagerDependencies): IdentityManager;
|
|
202
|
+
/**
|
|
203
|
+
* Creates a verification-only IdentityManager: same constructor, `config.identity` omitted.
|
|
204
|
+
*
|
|
205
|
+
* The returned manager supports identity verification, verified log loading, and cache
|
|
206
|
+
* eviction. Local signing, publication, and lifecycle mutation methods throw ArgumentError.
|
|
207
|
+
*/
|
|
208
|
+
declare function createIdentityVerifier(config: Omit<DnsidConfig, 'identity'>, deps: Omit<CreateIdentityManagerDependencies, 'keyProvider' | 'entityKeyProvider'>): IdentityManager;
|
|
209
|
+
|
|
210
|
+
export { type CreateIdentityManagerDependencies, type IssueManagedIdentityOptions, ManagedIssuanceActivationError, type ManagedIssuanceCoordination, type ManagedIssuanceRegistry, type ManagedIssuanceState, type ManagedIssuanceSubmission, ManagedIssuanceSubmissionError, ManagedKeyRotationActivationError, type ManagedKeyRotationRegistry, type ManagedKeyRotationResult, ManagedKeyRotationSubmissionError, type ResumeManagedIssuanceOptions, type ResumeManagedOperationalKeyRotationOptions, type RotateManagedOperationalKeyOptions, type SDKConformance, SDK_CONFORMANCE, createIdentityManager, createIdentityVerifier, issueManagedIdentity, resumeManagedIssuance, resumeManagedOperationalKeyRotation, rotateManagedOperationalKey };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
import { VerificationError, KeyProvider, DnsIdJWK, IdentityManagerDependencies, DnsidConfig, IdentityManager } from '@dnsid-ai/protocol';
|
|
2
|
+
export * from '@dnsid-ai/protocol';
|
|
3
|
+
export { ArgumentError, DNSID_VERSION, DNSSECMode, DNSSECState, DnsIdTxtRecord, DomainLog, DomainSnapshot, IdentityManager, InMemoryIdentityCache, JWKS, JWKS_MAX_RESPONSE_BYTES, LogRegistry, NoopLogReader, ParseError, SIGNING_ALGS, STATUS_MAX_RESPONSE_BYTES, ValidationError, VerificationCode, VerificationError, VerifiedDomain, activeStatusDocument, fromBase64Url, isDomainName, isTransientVerificationError, jwkSignatureAlg, jwkThumbprint, normalizeFQDN, parseKaDuration, parseKeyId, retryTransientVerification, toArrayBuffer, toBase64Url, validateAgentStatus, verifyWithKey } from '@dnsid-ai/protocol';
|
|
4
|
+
import * as jose from '@dnsid-ai/jose';
|
|
5
|
+
export { jose };
|
|
6
|
+
export { JoseProfile, createJoseProfile } from '@dnsid-ai/jose';
|
|
7
|
+
import * as httpSignatures from '@dnsid-ai/http-signatures';
|
|
8
|
+
export { httpSignatures };
|
|
9
|
+
export { HttpSignaturesProfile, createHttpSignaturesProfile } from '@dnsid-ai/http-signatures';
|
|
10
|
+
import { SubmissionResult, KeyRotationPreparationRequest, PreparedRegistryEvent } from '@dnsid-ai/registry';
|
|
11
|
+
import * as registry from '@dnsid-ai/registry';
|
|
12
|
+
export { registry };
|
|
13
|
+
export { DEFAULT_REGISTRY_URL, PreparedEventSubmissionError, RegistryClient, RegistryWorkflowError, awaitRegistryManagedPublication, publishClientControlledRecord, publishToRegistry } from '@dnsid-ai/registry';
|
|
14
|
+
import * as webBotAuth from '@dnsid-ai/web-bot-auth';
|
|
15
|
+
export { webBotAuth };
|
|
16
|
+
export { WebBotAuthProfile, createWebBotAuthProfile } from '@dnsid-ai/web-bot-auth';
|
|
17
|
+
|
|
18
|
+
interface ManagedKeyRotationRegistry {
|
|
19
|
+
prepareKeyRotation(domain: string, request: KeyRotationPreparationRequest, idempotencyKey: string): Promise<PreparedRegistryEvent>;
|
|
20
|
+
submitPreparedEvent(domain: string, entryBytes: Uint8Array, idempotencyKey: string): Promise<SubmissionResult>;
|
|
21
|
+
}
|
|
22
|
+
interface RotateManagedOperationalKeyOptions {
|
|
23
|
+
domain: string;
|
|
24
|
+
/** Exact unindexed c2sp-tlog reference configured for this identity. */
|
|
25
|
+
logReference: string;
|
|
26
|
+
keyProvider: KeyProvider;
|
|
27
|
+
registryClient: ManagedKeyRotationRegistry;
|
|
28
|
+
idempotencyKey: string;
|
|
29
|
+
/** Durably persists exact bytes and every subsequent reconciliation state. */
|
|
30
|
+
persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
|
|
31
|
+
/** Pauses application signing before submission and resumes it only after durable activation. */
|
|
32
|
+
setApplicationSigningPaused: (paused: boolean) => Promise<void>;
|
|
33
|
+
}
|
|
34
|
+
interface ManagedKeyRotationResult {
|
|
35
|
+
readonly domain: string;
|
|
36
|
+
readonly logReference: string;
|
|
37
|
+
readonly previousKid: string;
|
|
38
|
+
readonly newKid: string;
|
|
39
|
+
/**
|
|
40
|
+
* Persist these exact bytes with idempotencyKey while activated is false.
|
|
41
|
+
* Callers must pause new application signing until this rotation is accepted.
|
|
42
|
+
*/
|
|
43
|
+
readonly entryBytes: Uint8Array;
|
|
44
|
+
readonly idempotencyKey: string;
|
|
45
|
+
readonly submission?: SubmissionResult;
|
|
46
|
+
readonly activated: boolean;
|
|
47
|
+
readonly applicationSigningPaused: boolean;
|
|
48
|
+
}
|
|
49
|
+
interface ResumeManagedOperationalKeyRotationOptions {
|
|
50
|
+
keyProvider: KeyProvider;
|
|
51
|
+
registryClient: Pick<ManagedKeyRotationRegistry, 'submitPreparedEvent'>;
|
|
52
|
+
rotation: ManagedKeyRotationResult;
|
|
53
|
+
persistRotation: (rotation: ManagedKeyRotationResult) => Promise<void>;
|
|
54
|
+
setApplicationSigningPaused: (paused: boolean) => Promise<void>;
|
|
55
|
+
}
|
|
56
|
+
/** Submission failed after the completed entry bytes were fixed. */
|
|
57
|
+
declare class ManagedKeyRotationSubmissionError extends VerificationError {
|
|
58
|
+
readonly rotation: ManagedKeyRotationResult;
|
|
59
|
+
readonly retryWithSameBytes: boolean;
|
|
60
|
+
constructor(message: string, rotation: ManagedKeyRotationResult, retryWithSameBytes: boolean, cause?: unknown);
|
|
61
|
+
}
|
|
62
|
+
/** Registry acceptance succeeded, but local key-state reconciliation did not. */
|
|
63
|
+
declare class ManagedKeyRotationActivationError extends VerificationError {
|
|
64
|
+
readonly rotation: ManagedKeyRotationResult;
|
|
65
|
+
constructor(message: string, rotation: ManagedKeyRotationResult, cause?: unknown);
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Runs C2SP registry-managed rotation. The registry owns managed ku publication
|
|
69
|
+
* and append reconciliation; local activation happens only after an accepted
|
|
70
|
+
* result for the exact, durably persisted bytes while application signing is paused.
|
|
71
|
+
*/
|
|
72
|
+
declare function rotateManagedOperationalKey(options: RotateManagedOperationalKeyOptions): Promise<ManagedKeyRotationResult>;
|
|
73
|
+
/** Retries only the persisted completed bytes and activates on acceptance. */
|
|
74
|
+
declare function resumeManagedOperationalKeyRotation(options: ResumeManagedOperationalKeyRotationOptions): Promise<ManagedKeyRotationResult>;
|
|
75
|
+
|
|
76
|
+
interface ManagedIssuanceRegistry {
|
|
77
|
+
prepareIssuance(domain: string, idempotencyKey: string): Promise<PreparedRegistryEvent>;
|
|
78
|
+
submitPreparedEvent(domain: string, entryBytes: Uint8Array, idempotencyKey: string): Promise<SubmissionResult>;
|
|
79
|
+
}
|
|
80
|
+
interface ManagedIssuanceState {
|
|
81
|
+
readonly domain: string;
|
|
82
|
+
readonly governanceId: string;
|
|
83
|
+
readonly idempotencyKey: string;
|
|
84
|
+
readonly entityKid: string;
|
|
85
|
+
readonly entityThumbprint: string;
|
|
86
|
+
readonly operationalKid: string;
|
|
87
|
+
readonly operationalThumbprint: string;
|
|
88
|
+
/** Undefined only while the durable intent precedes remote preparation. */
|
|
89
|
+
readonly logReference?: string;
|
|
90
|
+
/** Exact completed canonical bytes. Undefined only for an intent. */
|
|
91
|
+
readonly entryBytes?: Uint8Array;
|
|
92
|
+
/** SHA-256 of entryBytes, persisted before the first submission. */
|
|
93
|
+
readonly entryHash?: string;
|
|
94
|
+
readonly submission?: ManagedIssuanceSubmission;
|
|
95
|
+
readonly terminalFailure?: {
|
|
96
|
+
readonly stage: 'preparation' | 'submission';
|
|
97
|
+
readonly errorCode?: string;
|
|
98
|
+
};
|
|
99
|
+
readonly activated: boolean;
|
|
100
|
+
}
|
|
101
|
+
type ManagedIssuanceSubmission = SubmissionResult | {
|
|
102
|
+
readonly state: 'indeterminate';
|
|
103
|
+
readonly entryHash: string;
|
|
104
|
+
readonly errorCode?: string;
|
|
105
|
+
};
|
|
106
|
+
interface ManagedIssuanceCoordination {
|
|
107
|
+
/** Loads the one durable setup operation, if it exists. */
|
|
108
|
+
loadIssuance: () => Promise<ManagedIssuanceState | undefined>;
|
|
109
|
+
/** Atomically creates the intent; returns the existing operation if the create lost a race. */
|
|
110
|
+
createIssuance: (intent: ManagedIssuanceState) => Promise<ManagedIssuanceState | undefined>;
|
|
111
|
+
/** Atomically persists the intent, exact bytes, and every reconciliation transition. */
|
|
112
|
+
persistIssuance: (issuance: ManagedIssuanceState) => Promise<void>;
|
|
113
|
+
/**
|
|
114
|
+
* Publishes/converges status only after exact-byte log acceptance is durably bound.
|
|
115
|
+
* Must be idempotent because a crash can replay it before `activated` is persisted.
|
|
116
|
+
*/
|
|
117
|
+
activateAcceptedIssuance: (issuance: ManagedIssuanceState) => Promise<void>;
|
|
118
|
+
}
|
|
119
|
+
interface IssueManagedIdentityOptions extends ManagedIssuanceCoordination {
|
|
120
|
+
domain: string;
|
|
121
|
+
governanceId: string;
|
|
122
|
+
/** Trusted accountable-entity public key whose existing `sigs.ae` is required. */
|
|
123
|
+
entityKey: DnsIdJWK;
|
|
124
|
+
operationalKeyProvider: KeyProvider;
|
|
125
|
+
registryClient: ManagedIssuanceRegistry;
|
|
126
|
+
idempotencyKey: string;
|
|
127
|
+
/** Optional configured reference; a registry response must match it exactly. */
|
|
128
|
+
logReference?: string;
|
|
129
|
+
}
|
|
130
|
+
interface ResumeManagedIssuanceOptions extends ManagedIssuanceCoordination {
|
|
131
|
+
entityKey: DnsIdJWK;
|
|
132
|
+
operationalKeyProvider: KeyProvider;
|
|
133
|
+
registryClient: ManagedIssuanceRegistry;
|
|
134
|
+
}
|
|
135
|
+
declare class ManagedIssuanceSubmissionError extends VerificationError {
|
|
136
|
+
readonly issuance: ManagedIssuanceState;
|
|
137
|
+
readonly retryWithSameBytes: boolean;
|
|
138
|
+
constructor(message: string, issuance: ManagedIssuanceState, retryWithSameBytes: boolean, transient: boolean, cause?: unknown);
|
|
139
|
+
}
|
|
140
|
+
declare class ManagedIssuanceActivationError extends VerificationError {
|
|
141
|
+
readonly issuance: ManagedIssuanceState;
|
|
142
|
+
constructor(issuance: ManagedIssuanceState, cause: unknown);
|
|
143
|
+
}
|
|
144
|
+
/** Starts one durable managed setup operation, or resumes the already persisted one. */
|
|
145
|
+
declare function issueManagedIdentity(options: IssueManagedIdentityOptions): Promise<ManagedIssuanceState>;
|
|
146
|
+
/** Resumes only the durable operation, reusing its preparation key or exact completed bytes. */
|
|
147
|
+
declare function resumeManagedIssuance(options: ResumeManagedIssuanceOptions): Promise<ManagedIssuanceState>;
|
|
148
|
+
|
|
149
|
+
/** Immutable protocol-facing conformance metadata for this SDK release. */
|
|
150
|
+
interface SDKConformance {
|
|
151
|
+
readonly publishProfile: string;
|
|
152
|
+
readonly verificationProfiles: Readonly<Record<string, string>>;
|
|
153
|
+
readonly specificationStatus: 'internet-draft' | 'rfc';
|
|
154
|
+
readonly logBindings: Readonly<Record<string, string>>;
|
|
155
|
+
readonly knownDeviations: readonly string[];
|
|
156
|
+
}
|
|
157
|
+
/** Exact DNSid profile and log-binding behavior implemented by this SDK release. */
|
|
158
|
+
declare const SDK_CONFORMANCE: SDKConformance;
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Runtime-neutral SDK entry point for DNSid.
|
|
162
|
+
*
|
|
163
|
+
* `@dnsid-ai/sdk` aggregates the DNSid TypeScript packages: it re-exports
|
|
164
|
+
* the full protocol core (`@dnsid-ai/protocol`), the registry client and
|
|
165
|
+
* publishing helpers, the JOSE, HTTP message signatures, and web bot auth
|
|
166
|
+
* profiles, and managed operational key rotation workflows.
|
|
167
|
+
*
|
|
168
|
+
* This root entry point makes no runtime assumptions: callers inject DNS resolution,
|
|
169
|
+
* JSON fetching, key-provider, cache, and log implementations (see
|
|
170
|
+
* {@link createIdentityManager}). Node conveniences — LocalKeyProvider, environment
|
|
171
|
+
* config loading, and Node identity manager factories — live behind the
|
|
172
|
+
* `@dnsid-ai/sdk/node` subpath. OIDC support deliberately lives in
|
|
173
|
+
* `@dnsid-ai/oidc` (Node-bound transport) and is not re-exported here.
|
|
174
|
+
*
|
|
175
|
+
* @packageDocumentation
|
|
176
|
+
*/
|
|
177
|
+
|
|
178
|
+
/** Runtime-neutral dependencies: DNS and JSON fetching must be injected. */
|
|
179
|
+
type CreateIdentityManagerDependencies = IdentityManagerDependencies & Required<Pick<IdentityManagerDependencies, 'dnsResolver' | 'fetchJson'>>;
|
|
180
|
+
/**
|
|
181
|
+
* Creates a DNSid IdentityManager from explicitly injected runtime dependencies.
|
|
182
|
+
*
|
|
183
|
+
* The root `@dnsid-ai/sdk` entrypoint is runtime-neutral: callers provide DNS, HTTPS/JSON
|
|
184
|
+
* fetching, key storage/signing, cache, and log implementations appropriate for Node,
|
|
185
|
+
* browsers, workers, wallets, HSMs, or application backends. Omit `config.identity` for a
|
|
186
|
+
* verification-only manager (see {@link createIdentityVerifier}).
|
|
187
|
+
*
|
|
188
|
+
* @example
|
|
189
|
+
* ```ts
|
|
190
|
+
* import { createIdentityManager } from '@dnsid-ai/sdk';
|
|
191
|
+
*
|
|
192
|
+
* const idm = createIdentityManager({ identity, verification }, {
|
|
193
|
+
* keyProvider, // operational key
|
|
194
|
+
* entityKeyProvider, // entity key
|
|
195
|
+
* dnsResolver, // DNSSEC-aware resolver
|
|
196
|
+
* fetchJson,
|
|
197
|
+
* });
|
|
198
|
+
* const verified = await idm.verifyDomain('agent.example.com');
|
|
199
|
+
* ```
|
|
200
|
+
*/
|
|
201
|
+
declare function createIdentityManager(config: DnsidConfig, deps: CreateIdentityManagerDependencies): IdentityManager;
|
|
202
|
+
/**
|
|
203
|
+
* Creates a verification-only IdentityManager: same constructor, `config.identity` omitted.
|
|
204
|
+
*
|
|
205
|
+
* The returned manager supports identity verification, verified log loading, and cache
|
|
206
|
+
* eviction. Local signing, publication, and lifecycle mutation methods throw ArgumentError.
|
|
207
|
+
*/
|
|
208
|
+
declare function createIdentityVerifier(config: Omit<DnsidConfig, 'identity'>, deps: Omit<CreateIdentityManagerDependencies, 'keyProvider' | 'entityKeyProvider'>): IdentityManager;
|
|
209
|
+
|
|
210
|
+
export { type CreateIdentityManagerDependencies, type IssueManagedIdentityOptions, ManagedIssuanceActivationError, type ManagedIssuanceCoordination, type ManagedIssuanceRegistry, type ManagedIssuanceState, type ManagedIssuanceSubmission, ManagedIssuanceSubmissionError, ManagedKeyRotationActivationError, type ManagedKeyRotationRegistry, type ManagedKeyRotationResult, ManagedKeyRotationSubmissionError, type ResumeManagedIssuanceOptions, type ResumeManagedOperationalKeyRotationOptions, type RotateManagedOperationalKeyOptions, type SDKConformance, SDK_CONFORMANCE, createIdentityManager, createIdentityVerifier, issueManagedIdentity, resumeManagedIssuance, resumeManagedOperationalKeyRotation, rotateManagedOperationalKey };
|