/
delegation.ts
403 lines (369 loc) · 12.6 KB
/
delegation.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
import {
DerEncodedPublicKey,
fromHex,
HttpAgentRequest,
PublicKey,
requestIdOf,
Signature,
SignIdentity,
toHex,
} from '@dfinity/agent';
import { Principal } from '@dfinity/principal';
import * as cbor from 'simple-cbor';
import { PartialIdentity } from './partial';
const domainSeparator = new TextEncoder().encode('\x1Aic-request-auth-delegation');
const requestDomainSeparator = new TextEncoder().encode('\x0Aic-request');
function _parseBlob(value: unknown): ArrayBuffer {
if (typeof value !== 'string' || value.length < 64) {
throw new Error('Invalid public key.');
}
return fromHex(value);
}
/**
* A single delegation object that is signed by a private key. This is constructed by
* `DelegationChain.create()`.
*
* {@see DelegationChain}
*/
export class Delegation {
constructor(
public readonly pubkey: ArrayBuffer,
public readonly expiration: bigint,
public readonly targets?: Principal[],
) {}
public toCBOR(): cbor.CborValue {
// Expiration field needs to be encoded as a u64 specifically.
return cbor.value.map({
pubkey: cbor.value.bytes(this.pubkey),
expiration: cbor.value.u64(this.expiration.toString(16), 16),
...(this.targets && {
targets: cbor.value.array(this.targets.map(t => cbor.value.bytes(t.toUint8Array()))),
}),
});
}
public toJSON(): JsonnableDelegation {
// every string should be hex and once-de-hexed,
// discoverable what it is (e.g. de-hex to get JSON with a 'type' property, or de-hex to DER
// with an OID). After de-hex, if it's not obvious what it is, it's an ArrayBuffer.
return {
expiration: this.expiration.toString(16),
pubkey: toHex(this.pubkey),
...(this.targets && { targets: this.targets.map(p => p.toHex()) }),
};
}
}
/**
* Type of ReturnType<Delegation.toJSON>.
* The goal here is to stringify all non-JSON-compatible types to some bytes representation we can
* stringify as hex.
* (Hex shouldn't be ambiguous ever, because you can encode as DER with semantic OIDs).
*/
interface JsonnableDelegation {
// A BigInt of Nanoseconds since epoch as hex
expiration: string;
// Hexadecimal representation of the DER public key.
pubkey: string;
// Array of strings, where each string is hex of principal blob (*NOT* textual representation).
targets?: string[];
}
/**
* A signed delegation, which lends its identity to the public key in the delegation
* object. This is constructed by `DelegationChain.create()`.
*
* {@see DelegationChain}
*/
export interface SignedDelegation {
delegation: Delegation;
signature: Signature;
}
/**
* Sign a single delegation object for a period of time.
* @param from The identity that lends its delegation.
* @param to The identity that receives the delegation.
* @param expiration An expiration date for this delegation.
* @param targets Limit this delegation to the target principals.
*/
async function _createSingleDelegation(
from: SignIdentity,
to: PublicKey,
expiration: Date,
targets?: Principal[],
): Promise<SignedDelegation> {
const delegation: Delegation = new Delegation(
to.toDer(),
BigInt(+expiration) * BigInt(1000000), // In nanoseconds.
targets,
);
// The signature is calculated by signing the concatenation of the domain separator
// and the message.
// Note: To ensure Safari treats this as a user gesture, ensure to not use async methods
// besides the actualy webauthn functionality (such as `sign`). Safari will de-register
// a user gesture if you await an async call thats not fetch, xhr, or setTimeout.
const challenge = new Uint8Array([
...domainSeparator,
...new Uint8Array(requestIdOf(delegation)),
]);
const signature = await from.sign(challenge);
return {
delegation,
signature,
};
}
export interface JsonnableDelegationChain {
publicKey: string;
delegations: Array<{
signature: string;
delegation: {
pubkey: string;
expiration: string;
targets?: string[];
};
}>;
}
/**
* A chain of delegations. This is JSON Serializable.
* This is the object to serialize and pass to a DelegationIdentity. It does not keep any
* private keys.
*/
export class DelegationChain {
/**
* Create a delegation chain between two (or more) keys. By default, the expiration time
* will be very short (15 minutes).
*
* To build a chain of more than 2 identities, this function needs to be called multiple times,
* passing the previous delegation chain into the options argument. For example:
* @example
* const rootKey = createKey();
* const middleKey = createKey();
* const bottomeKey = createKey();
*
* const rootToMiddle = await DelegationChain.create(
* root, middle.getPublicKey(), Date.parse('2100-01-01'),
* );
* const middleToBottom = await DelegationChain.create(
* middle, bottom.getPublicKey(), Date.parse('2100-01-01'), { previous: rootToMiddle },
* );
*
* // We can now use a delegation identity that uses the delegation above:
* const identity = DelegationIdentity.fromDelegation(bottomKey, middleToBottom);
* @param from The identity that will delegate.
* @param to The identity that gets delegated. It can now sign messages as if it was the
* identity above.
* @param expiration The length the delegation is valid. By default, 15 minutes from calling
* this function.
* @param options A set of options for this delegation. expiration and previous
* @param options.previous - Another DelegationChain that this chain should start with.
* @param options.targets - targets that scope the delegation (e.g. Canister Principals)
*/
public static async create(
from: SignIdentity,
to: PublicKey,
expiration: Date = new Date(Date.now() + 15 * 60 * 1000),
options: {
previous?: DelegationChain;
targets?: Principal[];
} = {},
): Promise<DelegationChain> {
const delegation = await _createSingleDelegation(from, to, expiration, options.targets);
return new DelegationChain(
[...(options.previous?.delegations || []), delegation],
options.previous?.publicKey || from.getPublicKey().toDer(),
);
}
/**
* Creates a DelegationChain object from a JSON string.
* @param json The JSON string to parse.
*/
public static fromJSON(json: string | JsonnableDelegationChain): DelegationChain {
const { publicKey, delegations } = typeof json === 'string' ? JSON.parse(json) : json;
if (!Array.isArray(delegations)) {
throw new Error('Invalid delegations.');
}
const parsedDelegations: SignedDelegation[] = delegations.map(signedDelegation => {
const { delegation, signature } = signedDelegation;
const { pubkey, expiration, targets } = delegation;
if (targets !== undefined && !Array.isArray(targets)) {
throw new Error('Invalid targets.');
}
return {
delegation: new Delegation(
_parseBlob(pubkey),
BigInt('0x' + expiration), // expiration in JSON is an hexa string (See toJSON() below).
targets &&
targets.map((t: unknown) => {
if (typeof t !== 'string') {
throw new Error('Invalid target.');
}
return Principal.fromHex(t);
}),
),
signature: _parseBlob(signature) as Signature,
};
});
return new this(parsedDelegations, _parseBlob(publicKey) as DerEncodedPublicKey);
}
/**
* Creates a DelegationChain object from a list of delegations and a DER-encoded public key.
* @param delegations The list of delegations.
* @param publicKey The DER-encoded public key of the key-pair signing the first delegation.
*/
public static fromDelegations(
delegations: SignedDelegation[],
publicKey: DerEncodedPublicKey,
): DelegationChain {
return new this(delegations, publicKey);
}
protected constructor(
public readonly delegations: SignedDelegation[],
public readonly publicKey: DerEncodedPublicKey,
) {}
public toJSON(): JsonnableDelegationChain {
return {
delegations: this.delegations.map(signedDelegation => {
const { delegation, signature } = signedDelegation;
const { targets } = delegation;
return {
delegation: {
expiration: delegation.expiration.toString(16),
pubkey: toHex(delegation.pubkey),
...(targets && {
targets: targets.map(t => t.toHex()),
}),
},
signature: toHex(signature),
};
}),
publicKey: toHex(this.publicKey),
};
}
}
/**
* An Identity that adds delegation to a request. Everywhere in this class, the name
* innerKey refers to the SignIdentity that is being used to sign the requests, while
* originalKey is the identity that is being borrowed. More identities can be used
* in the middle to delegate.
*/
export class DelegationIdentity extends SignIdentity {
/**
* Create a delegation without having access to delegateKey.
* @param key The key used to sign the reqyests.
* @param delegation A delegation object created using `createDelegation`.
*/
public static fromDelegation(
key: Pick<SignIdentity, 'sign'>,
delegation: DelegationChain,
): DelegationIdentity {
return new this(key, delegation);
}
protected constructor(
private _inner: Pick<SignIdentity, 'sign'>,
private _delegation: DelegationChain,
) {
super();
}
public getDelegation(): DelegationChain {
return this._delegation;
}
public getPublicKey(): PublicKey {
return {
derKey: this._delegation.publicKey,
toDer: () => this._delegation.publicKey,
};
}
public sign(blob: ArrayBuffer): Promise<Signature> {
return this._inner.sign(blob);
}
public async transformRequest(request: HttpAgentRequest): Promise<unknown> {
const { body, ...fields } = request;
const requestId = await requestIdOf(body);
return {
...fields,
body: {
content: body,
sender_sig: await this.sign(
new Uint8Array([...requestDomainSeparator, ...new Uint8Array(requestId)]),
),
sender_delegation: this._delegation.delegations,
sender_pubkey: this._delegation.publicKey,
},
};
}
}
/**
* A partial delegated identity, representing a delegation chain and the public key that it targets
*/
export class PartialDelegationIdentity extends PartialIdentity {
#delegation: DelegationChain;
/**
* The Delegation Chain of this identity.
*/
get delegation(): DelegationChain {
return this.#delegation;
}
private constructor(inner: PublicKey, delegation: DelegationChain) {
super(inner);
this.#delegation = delegation;
}
/**
* Create a {@link PartialDelegationIdentity} from a {@link PublicKey} and a {@link DelegationChain}.
* @param key The {@link PublicKey} to delegate to.
* @param delegation a {@link DelegationChain} targeting the inner key.
* @constructs PartialDelegationIdentity
*/
public static fromDelegation(key: PublicKey, delegation: DelegationChain) {
return new PartialDelegationIdentity(key, delegation);
}
}
/**
* List of things to check for a delegation chain validity.
*/
export interface DelegationValidChecks {
/**
* Check that the scope is amongst the scopes that this delegation has access to.
*/
scope?: Principal | string | Array<Principal | string>;
}
/**
* Analyze a DelegationChain and validate that it's valid, ie. not expired and apply to the
* scope.
* @param chain The chain to validate.
* @param checks Various checks to validate on the chain.
*/
export function isDelegationValid(chain: DelegationChain, checks?: DelegationValidChecks): boolean {
// Verify that the no delegation is expired. If any are in the chain, returns false.
for (const { delegation } of chain.delegations) {
// prettier-ignore
if (+new Date(Number(delegation.expiration / BigInt(1000000))) <= +Date.now()) {
return false;
}
}
// Check the scopes.
const scopes: Principal[] = [];
const maybeScope = checks?.scope;
if (maybeScope) {
if (Array.isArray(maybeScope)) {
scopes.push(...maybeScope.map(s => (typeof s === 'string' ? Principal.fromText(s) : s)));
} else {
scopes.push(typeof maybeScope === 'string' ? Principal.fromText(maybeScope) : maybeScope);
}
}
for (const s of scopes) {
const scope = s.toText();
for (const { delegation } of chain.delegations) {
if (delegation.targets === undefined) {
continue;
}
let none = true;
for (const target of delegation.targets) {
if (target.toText() === scope) {
none = false;
break;
}
}
if (none) {
return false;
}
}
}
return true;
}