@kokuin/vault 0.0.0-stage → 0.7.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.
package/lib/index.js ADDED
@@ -0,0 +1,12 @@
1
+ export * from './branch.js';
2
+ export * from './canonical-token.js';
3
+ export * from './digest.js';
4
+ export * from './errors.js';
5
+ export * from './factors.js';
6
+ export * from './id.js';
7
+ export * from './key-cache.js';
8
+ export * from './pin-throttle.js';
9
+ export * from './record-types.js';
10
+ export { decodeVaultRecord, encodeVaultRecordPayload, VAULT_OP_KIND, VAULT_RECORD_TYPES, VaultRecordPayloadError, vaultRecordMeta, vaultRevocationRecordID } from './records.js';
11
+ export * from './suite.js';
12
+ export * from './wrappable.js';
@@ -0,0 +1,35 @@
1
+ export type KeyCacheSetParams = {
2
+ keyID: string;
3
+ contentKey: Uint8Array;
4
+ keyVersion: number;
5
+ branchID: string;
6
+ };
7
+ export declare const DEFAULT_UNLOCK_TTL: number;
8
+ export type KeyCacheParams = {
9
+ ttl?: number;
10
+ now?: () => number;
11
+ };
12
+ export type KeyCache = {
13
+ get(params: KeyCacheGetParams): {
14
+ contentKey: Uint8Array;
15
+ branchID: string;
16
+ } | null;
17
+ has(params: KeyCacheHasParams): boolean;
18
+ set(params: KeyCacheSetParams): void;
19
+ evictVersion(params: KeyCacheEvictVersionParams): void;
20
+ evict(keyID: string): void;
21
+ evictAll(): void;
22
+ };
23
+ export declare function createKeyCache(params?: KeyCacheParams): KeyCache;
24
+ export type KeyCacheGetParams = {
25
+ keyID: string;
26
+ keyVersion: number;
27
+ };
28
+ export type KeyCacheHasParams = {
29
+ keyID: string;
30
+ keyVersion: number;
31
+ };
32
+ export type KeyCacheEvictVersionParams = {
33
+ keyID: string;
34
+ keyVersion: number;
35
+ };
@@ -0,0 +1,65 @@
1
+ export const DEFAULT_UNLOCK_TTL = 15 * 60 * 1000;
2
+ export function createKeyCache(params = {}) {
3
+ const ttl = params.ttl ?? DEFAULT_UNLOCK_TTL;
4
+ const now = params.now ?? Date.now;
5
+ const entries = new Map();
6
+ function evict(keyID) {
7
+ const versions = entries.get(keyID);
8
+ if (versions == null) return;
9
+ for (const cached of versions.values())cached.contentKey.fill(0);
10
+ entries.delete(keyID);
11
+ }
12
+ function evictVersion(keyID, keyVersion) {
13
+ const versions = entries.get(keyID);
14
+ const cached = versions?.get(keyVersion);
15
+ if (cached == null) return;
16
+ cached.contentKey.fill(0);
17
+ versions?.delete(keyVersion);
18
+ if (versions?.size === 0) entries.delete(keyID);
19
+ }
20
+ function live(keyID, keyVersion) {
21
+ const cached = entries.get(keyID)?.get(keyVersion);
22
+ if (cached == null) {
23
+ return null;
24
+ }
25
+ if (now() - cached.unlockedAt >= ttl) {
26
+ evictVersion(keyID, keyVersion);
27
+ return null;
28
+ }
29
+ return cached;
30
+ }
31
+ return {
32
+ get ({ keyID, keyVersion }) {
33
+ const cached = live(keyID, keyVersion);
34
+ if (cached == null) {
35
+ return null;
36
+ }
37
+ return {
38
+ contentKey: cached.contentKey.slice(),
39
+ branchID: cached.branchID
40
+ };
41
+ },
42
+ has ({ keyID, keyVersion }) {
43
+ return live(keyID, keyVersion) != null;
44
+ },
45
+ set ({ keyID, contentKey, keyVersion, branchID }) {
46
+ evictVersion(keyID, keyVersion);
47
+ const versions = entries.get(keyID) ?? new Map();
48
+ versions.set(keyVersion, {
49
+ contentKey: contentKey.slice(),
50
+ branchID,
51
+ unlockedAt: now()
52
+ });
53
+ entries.set(keyID, versions);
54
+ },
55
+ evict,
56
+ evictVersion: ({ keyID, keyVersion })=>evictVersion(keyID, keyVersion),
57
+ evictAll () {
58
+ for (const keyID of [
59
+ ...entries.keys()
60
+ ]){
61
+ evict(keyID);
62
+ }
63
+ }
64
+ };
65
+ }
@@ -0,0 +1,16 @@
1
+ export declare const DEFAULT_FREE_ATTEMPTS = 3;
2
+ export declare const DEFAULT_BASE_DELAY = 1000;
3
+ export declare const DEFAULT_MAX_DELAY: number;
4
+ export type PinThrottleParams = {
5
+ freeAttempts?: number;
6
+ baseDelay?: number;
7
+ maxDelay?: number;
8
+ now?: () => number;
9
+ };
10
+ export type PinThrottle = {
11
+ retryAfter(keyID: string): number;
12
+ attemptsRemaining(keyID: string): number;
13
+ recordFailure(keyID: string): void;
14
+ recordSuccess(keyID: string): void;
15
+ };
16
+ export declare function createPinThrottle(params?: PinThrottleParams): PinThrottle;
@@ -0,0 +1,40 @@
1
+ export const DEFAULT_FREE_ATTEMPTS = 3;
2
+ export const DEFAULT_BASE_DELAY = 1000;
3
+ export const DEFAULT_MAX_DELAY = 15 * 60 * 1000;
4
+ export function createPinThrottle(params = {}) {
5
+ const freeAttempts = params.freeAttempts ?? DEFAULT_FREE_ATTEMPTS;
6
+ const baseDelay = params.baseDelay ?? DEFAULT_BASE_DELAY;
7
+ const maxDelay = params.maxDelay ?? DEFAULT_MAX_DELAY;
8
+ const now = params.now ?? Date.now;
9
+ const attempts = new Map();
10
+ function delayAfter(failures) {
11
+ if (failures < freeAttempts) {
12
+ return 0;
13
+ }
14
+ return Math.min(baseDelay * 2 ** (failures - freeAttempts), maxDelay);
15
+ }
16
+ return {
17
+ retryAfter (keyID) {
18
+ const record = attempts.get(keyID);
19
+ if (record == null) {
20
+ return 0;
21
+ }
22
+ const elapsed = now() - record.lastFailureAt;
23
+ return Math.max(0, delayAfter(record.failures) - elapsed);
24
+ },
25
+ attemptsRemaining (keyID) {
26
+ const record = attempts.get(keyID);
27
+ return Math.max(0, freeAttempts - (record?.failures ?? 0));
28
+ },
29
+ recordFailure (keyID) {
30
+ const record = attempts.get(keyID);
31
+ attempts.set(keyID, {
32
+ failures: (record?.failures ?? 0) + 1,
33
+ lastFailureAt: now()
34
+ });
35
+ },
36
+ recordSuccess (keyID) {
37
+ attempts.delete(keyID);
38
+ }
39
+ };
40
+ }
@@ -0,0 +1,55 @@
1
+ import type { RecordKey, RecordStoreAdapter, RecordTypeDefinition, SignedRecord, VerifiedRecordOp, VisibilityContext } from '@kokuin/records';
2
+ import type { CryptoOptions, MethodRegistry } from '@kokuin/token';
3
+ export type CredentialRecordReadPort = Pick<RecordStoreAdapter, 'get' | 'getMany' | 'list'>;
4
+ export type CredentialAuthorityRequest = {
5
+ source: 'record';
6
+ op: VerifiedRecordOp;
7
+ owner: string;
8
+ issuer: string;
9
+ verb: 'read' | 'administer';
10
+ recordKey: RecordKey;
11
+ transportContext: unknown;
12
+ record: SignedRecord;
13
+ store: CredentialRecordReadPort;
14
+ };
15
+ export type CredentialAuthority = {
16
+ authorize(request: CredentialAuthorityRequest): Promise<boolean>;
17
+ };
18
+ export type VaultKeyAddress = {
19
+ ownerDID: string;
20
+ keyID: string;
21
+ };
22
+ export type VaultRecordPorts = {
23
+ retainEntryCandidate(record: SignedRecord): Promise<void>;
24
+ listRevocations(address: VaultKeyAddress): Promise<Array<string>>;
25
+ dropRevokedWrappings(address: VaultKeyAddress): Promise<void>;
26
+ };
27
+ export type VaultRecordHooks = {
28
+ authority: CredentialAuthority;
29
+ validateConsumerMetadata(params: VaultRecordHooksValidateConsumerMetadataParams): Promise<boolean>;
30
+ /** Must resolve ports bound to this adapter's transaction, including routed adapters. */
31
+ portsFor(store: RecordStoreAdapter): VaultRecordPorts;
32
+ };
33
+ export type VaultRecordTypeParams = VaultRecordHooks & CryptoOptions & {
34
+ opKind: string;
35
+ methods?: MethodRegistry;
36
+ };
37
+ /** One explicit replay domain and consumer policy for the five generic record types. */
38
+ export declare function vaultRecordTypes(input: VaultRecordTypeParams): Map<string, RecordTypeDefinition>;
39
+ /** Only wrappings can prove key holding, regardless of other records' metadata. */
40
+ export declare function vaultHolderTypes(types: ReadonlyMap<string, RecordTypeDefinition>): ReadonlyMap<string, RecordTypeDefinition>;
41
+ /** Read a live, owner-qualified key version in the explicit replay domain. */
42
+ export type VaultKeyVersionReaderParams = {
43
+ store: RecordStoreAdapter;
44
+ } & Pick<VaultRecordTypeParams, 'opKind' | 'methods' | 'crypto'>;
45
+ export declare function vaultKeyVersionReader(input: VaultKeyVersionReaderParams): VisibilityContext['currentKeyVersion'];
46
+ /** Proofs retain consumer authority checks but are never addressed to the local receiver. */
47
+ export type VaultProofAuthorizerParams = {
48
+ store: RecordStoreAdapter;
49
+ transportContext?: unknown;
50
+ } & VaultRecordTypeParams;
51
+ export declare function vaultProofAuthorizer(input: VaultProofAuthorizerParams): VisibilityContext['authorizeProof'];
52
+ export type VaultRecordHooksValidateConsumerMetadataParams = {
53
+ value: unknown;
54
+ request: CredentialAuthorityRequest;
55
+ };