@verdant-web/common 2.3.4 → 2.4.0-next.1

package/src/authz.ts

@@ -0,0 +1,74 @@
+import { DocumentBaseline } from './baseline.js';
+import { Operation } from './operation.js';
+
+function encode(str: string): AuthorizationKey {
+	if (typeof Buffer !== 'undefined') {
+		const val = Buffer.from(str).toString('base64');
+		return val as AuthorizationKey;
+	}
+	const val = btoa(str);
+	return val as AuthorizationKey;
+}
+
+function decode(str: string): string {
+	if (typeof Buffer !== 'undefined') {
+		return Buffer.from(str, 'base64').toString();
+	}
+	return atob(str);
+}
+
+export type AuthorizationKey = string & {
+	'@@type': 'authz';
+};
+
+export const authz = {
+	onlyUser: (userId: string): AuthorizationKey => encode(`u:${userId}:*`),
+	onlyMe: (): AuthorizationKey => authz.onlyUser(ORIGINATOR_SUBJECT),
+	decode: (encoded: string) => {
+		const decoded = decode(encoded);
+		const parts = decoded.split(':');
+		if (parts.length !== 3) {
+			throw new Error('Invalid authz string');
+		}
+		return {
+			scope: parts[0],
+			subject: parts[1],
+			action: parts[2],
+		};
+	},
+};
+
+export const ORIGINATOR_SUBJECT = '$$_originator_$$';
+
+/**
+ * Rewrites the special "originator" constant subject (used by
+ * local-only clients) to the given user ID.
+ *
+ * Used to initialize a library from a local-only replica
+ */
+export function rewriteAuthzOriginator(
+	data: { operations?: Operation[]; baselines?: DocumentBaseline[] },
+	newSubject: string,
+) {
+	const { operations, baselines } = data;
+	if (operations) {
+		for (const op of operations) {
+			if (op.authz) {
+				const decoded = authz.decode(op.authz);
+				if (decoded.subject === ORIGINATOR_SUBJECT) {
+					op.authz = authz.onlyUser(newSubject);
+				}
+			}
+		}
+	}
+	if (baselines) {
+		for (const baseline of baselines) {
+			if (baseline.authz) {
+				const decoded = authz.decode(baseline.authz);
+				if (decoded.subject === ORIGINATOR_SUBJECT) {
+					baseline.authz = authz.onlyUser(newSubject);
+				}
+			}
+		}
+	}
+}

package/src/baseline.ts

@@ -1,9 +1,10 @@
+// A: Docs without a base state don't have a baseline, it's
+// written upon rebasing. If you apply ops to an undefined
+// snapshot without an initialize, it remains undefined.
+
 export type DocumentBaseline<T extends any = any> = {
 	oid: string;
 	snapshot: T;
 	timestamp: string;
-	// TODO: is a deleted flag required here? can we disambiguate
-	// a document which was snapshotted in a deleted state, vs
-	// one without a base state at all? what happens if you apply
-	// ops onto an undefined snapshot (which aren't initialize)?
+	authz?: string;
 };

package/src/files.ts

@@ -1,3 +1,5 @@
+import { isObject } from './utils.js';
+
 export type FileRef = {
 	'@@type': 'file';
 	id: string;
@@ -22,7 +24,9 @@ export type FileData = {
 	remote: boolean;
 	name: string;
 	type: string;
+	/** A local File instance, if available. */
 	file?: Blob;
+	/** The server URL of this file. */
 	url?: string;
 };
 
@@ -32,3 +36,24 @@ export function getAllFileFields(snapshot: any): [string, FileRef][] {
 		FileRef,
 	][];
 }
+
+export function isFile(value: any) {
+	if (typeof File !== 'undefined' && value instanceof File) {
+		return true;
+	}
+	if (typeof Blob !== 'undefined' && value instanceof Blob) {
+		return true;
+	}
+	return false;
+}
+
+export function isFileData(value: any): value is FileData {
+	return (
+		value &&
+		isObject(value) &&
+		typeof value.id === 'string' &&
+		typeof value.remote === 'boolean' &&
+		typeof value.name === 'string' &&
+		typeof value.type === 'string'
+	);
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export type {
 export type { UserInfo } from './presence.js';
 export * from './patch.js';
 export * from './oids.js';
+export * from './oidsLegacy.js';
 export * from './EventSubscriber.js';
 export * from './undo.js';
 export * from './batching.js';
@@ -28,3 +29,4 @@ export type { Ref } from './refs.js';
 export { makeObjectRef, makeFileRef, isRef, compareRefs } from './refs.js';
 export * from './memo.js';
 export * from './error.js';
+export * from './authz.js';

package/src/indexes.test.ts

@@ -185,7 +185,7 @@ describe('all indexes', () => {
 			),
 		).toEqual({
 			foobar: 'foo' + COMPOUND_INDEX_SEPARATOR + 'foobar',
-			'@@@snapshot': { foo: 'foo' },
+			'@@@snapshot': JSON.stringify({ foo: 'foo' }),
 			foo: 'foo',
 			bar: 'foobar',
 		});

package/src/indexes.ts

@@ -161,7 +161,7 @@ export function getIndexValues(
 		basicIndexes,
 		computeCompoundIndices(schema, { ...doc, ...basicIndexes }),
 	);
-	basicIndexes['@@@snapshot'] = doc;
+	basicIndexes['@@@snapshot'] = JSON.stringify(doc);
 	return basicIndexes;
 }
 

package/src/migration.ts

@@ -13,6 +13,7 @@ import {
 	getOid,
 	hasDefault,
 	validateEntity,
+	AuthorizationKey,
 } from './index.js';
 
 /**@deprecated */
@@ -473,7 +474,10 @@ type MigrationQueries<Old extends SchemaDocuments> = {
 };
 type MigrationMutations<New extends SchemaDocuments> = {
 	[Key in keyof New]: {
-		put(document: New[Key]['init']): Promise<New[Key]['snapshot']>;
+		put(
+			document: New[Key]['init'],
+			options?: { access?: AuthorizationKey },
+		): Promise<New[Key]['snapshot']>;
 		delete(primaryKey: string): Promise<void>;
 	};
 };

package/src/oids.test.ts

@@ -1,27 +1,15 @@
 import { describe, expect, it } from 'vitest';
 import { createFileRef } from './files.js';
 import {
-	areOidsRelated,
 	assignOid,
-	assignOidPropertiesToAllSubObjects,
-	assignOidProperty,
 	assignOidsToAllSubObjects,
 	createOid,
-	createSubOid,
 	decomposeOid,
-	getOid,
 	getOidSubIdRange,
-	getOidRoot,
 	hasOid,
-	maybeGetOidProperty,
 	normalize,
 	normalizeFirstLevel,
 	ObjectIdentifier,
-	removeOidPropertiesFromAllSubObjects,
-	getLegacyDotOidSubIdRange,
-	replaceLegacyOidsInJsonString,
-	MATCH_LEGACY_OID_JSON_STRING,
-	replaceLegacyOidsInObject,
 } from './oids.js';
 
 describe('normalizing an object', () => {
@@ -280,127 +268,6 @@ describe('computing a range of oids for a whole object set', () => {
 		expect(isWithin('test/a1', start, end)).toBe(false);
 		expect(isWithin('test/a1:3', start, end)).toBe(false);
 	});
-	it('should accommodate legacy dot style oids', () => {
-		const [start, end] = getLegacyDotOidSubIdRange('test/a.foo:barrrr');
-		expect(start).toEqual('test/a.');
-		expect(end).toEqual('test/a.\uffff');
-		expect(start < end).toBe(true);
-		expect(isWithin('test/a.foo:0', start, end)).toBe(true);
-		expect(isWithin('test/a.foo:1', start, end)).toBe(true);
-		expect(isWithin('test/a.bar:zzzzzzzzzzzzzzzzzzzzzzz', start, end)).toBe(
-			true,
-		);
-		expect(isWithin('test/a.aff:\uffff', start, end)).toBe(true);
-		expect(isWithin('test1/a', start, end)).toBe(false);
-		expect(isWithin('test/b', start, end)).toBe(false);
-		expect(isWithin('test/ ', start, end)).toBe(false);
-		expect(isWithin('test/a1', start, end)).toBe(false);
-		expect(isWithin('test/a1:3', start, end)).toBe(false);
-		expect(isWithin('test/a.foo:barrrr', start, end)).toBe(true);
-	});
-});
-
-describe('assigning OIDs as properties', () => {
-	it('should assign to all sub-objects', () => {
-		let i = 0;
-		function createSubId() {
-			return (i++).toString();
-		}
-
-		const initial = {
-			foo: {
-				bar: 1,
-				baz: [2, 3],
-			},
-			qux: [
-				{
-					corge: true,
-				},
-				{
-					grault: {
-						garply: 4,
-					},
-				},
-			],
-		};
-		assignOid(initial, 'test/a');
-		assignOidsToAllSubObjects(initial, createSubId);
-		assignOidPropertiesToAllSubObjects(initial);
-
-		expect(initial).toMatchInlineSnapshot(`
-			{
-			  "@@id": "test/a",
-			  "foo": {
-			    "@@id": "test/a:0",
-			    "bar": 1,
-			    "baz": [
-			      2,
-			      3,
-			    ],
-			  },
-			  "qux": [
-			    {
-			      "@@id": "test/a:3",
-			      "corge": true,
-			    },
-			    {
-			      "@@id": "test/a:4",
-			      "grault": {
-			        "@@id": "test/a:5",
-			        "garply": 4,
-			      },
-			    },
-			  ],
-			}
-		`);
-		// extra check needed for array since it doesn't serialize in the snapshot
-		expect(maybeGetOidProperty(initial.qux)).toBe('test/a:2');
-	});
-
-	it('should transfer assigned OID properties to the memory system', () => {
-		const initial = assignOidProperty(
-			{
-				foo: assignOidProperty(
-					{
-						bar: 1,
-					},
-					'test/a:1',
-				),
-				qux: assignOidProperty(
-					[
-						assignOidProperty(
-							{
-								corge: true,
-							},
-							'test/a:2',
-						),
-						assignOidProperty(
-							{
-								grault: assignOidProperty(
-									{
-										garply: 4,
-									},
-									'test/a:3',
-								),
-							},
-							'test/a:4',
-						),
-					],
-					'test/a:2',
-				),
-			},
-			'test/a',
-		);
-
-		removeOidPropertiesFromAllSubObjects(initial);
-
-		expect(getOid(initial)).toEqual('test/a');
-		expect(getOid(initial.foo)).toEqual('test/a:1');
-		expect(getOid(initial.qux)).toEqual('test/a:2');
-		expect(getOid(initial.qux[0])).toEqual('test/a:2');
-		expect(getOid(initial.qux[1])).toEqual('test/a:4');
-		expect(getOid(initial.qux[1].grault)).toEqual('test/a:3');
-	});
 });
 
 it('should handle special characters in document id or collection', () => {
@@ -430,111 +297,3 @@ describe('assigning OIDs to sub-objects', () => {
 		expect(hasOid(obj.bar[0])).toBe(false);
 	});
 });
-
-describe('handling legacy OIDs', () => {
-	it('should get the root OID for a legacy OID', () => {
-		expect(getOidRoot('items/clabgyjfh00003968qycsq3ld.inputs.#')).toEqual(
-			'items/clabgyjfh00003968qycsq3ld',
-		);
-	});
-	it('should create sub-ids for legacy OIDs in new format', () => {
-		expect(
-			createSubOid(
-				'items/clabgyjfh00003968qycsq3ld.inputs.#',
-				() => 'pseudorandom',
-			),
-		).toEqual('items/clabgyjfh00003968qycsq3ld:pseudorandom');
-	});
-	it('should identify new sub-OIDs as related to the legacy root OID', () => {
-		expect(
-			areOidsRelated(
-				'items/clabgyjfh00003968qycsq3ld.inputs.#',
-				'items/clabgyjfh00003968qycsq3ld:pseudorandom',
-			),
-		).toBe(true);
-	});
-	it.each([
-		['items/clabgyjfh00003968qycsq3ld.inputs.#:baz', true],
-		// include more unicode chars
-		['items/clabgyjfh00003968qycsq3ld\ufea3.inputs\u39fc.#:baz!!!', true],
-		// not matching new oids
-		['items/clabgyjfh00003968qycsq3ld', false],
-		['items/clabgyjfh00003968qycsq3ld:baz', false],
-		['items/clabgyjfh00003968qycsq3ld:baz1111', false],
-		// not matching anything else
-		[
-			'PREPARE SOUS VIDE BATH: Fill container or pot with water. Set the temperature to 130F/54.4C – 132F/55.5C (for very moist and tender) and allow water to heat to that temperature.Tip: start with hot tap water instead of cold water to reduce heating time. Note 4 for other temperatures.',
-			false,
-		],
-	])('matches legacy oids', (oid, match) => {
-		expect(MATCH_LEGACY_OID_JSON_STRING.test('"' + oid + '"'), oid).toBe(match);
-		// regex are stateful 🙄
-		MATCH_LEGACY_OID_JSON_STRING.lastIndex = 0;
-	});
-	it.each([
-		[
-			{ op: 'delete', oid: 'items/clabgyjfh00003968qycsq3ld.inputs.#:baz' },
-			{ op: 'delete', oid: 'items/clabgyjfh00003968qycsq3ld:baz' },
-		],
-		[
-			{
-				op: 'list-push',
-				oid: 'items/clabgyjfh00003968qycsq3ld.inputs.#:baz',
-				value: {
-					'@@type': 'ref',
-					id: 'items/clabgyjfh00003968qycsq3ld.inputs.#:qux',
-				},
-			},
-			{
-				op: 'list-push',
-				oid: 'items/clabgyjfh00003968qycsq3ld:baz',
-				value: { '@@type': 'ref', id: 'items/clabgyjfh00003968qycsq3ld:qux' },
-			},
-		],
-		[
-			{
-				op: 'list-remove',
-				oid: 'items/clabgyjfh00003968qycsq3ld.inputs.#:baz',
-				value: {
-					'@@type': 'ref',
-					id: 'items/clabgyjfh00003968qycsq3ld.inputs.#:qux',
-				},
-			},
-			{
-				op: 'list-remove',
-				oid: 'items/clabgyjfh00003968qycsq3ld:baz',
-				value: { '@@type': 'ref', id: 'items/clabgyjfh00003968qycsq3ld:qux' },
-			},
-		],
-		[
-			{
-				oid: 'items/clabgyjfh00003968qycsq3ld.inputs.#:baz',
-				timestamp: '2021-03-04T21:00:00.000Z',
-				snapshot: {
-					foo: 1,
-					bar: {
-						'@@type': 'ref',
-						id: 'items/clabgyjfh00003968qycsq3ld.inputs.#:qux',
-					},
-				},
-			},
-			{
-				oid: 'items/clabgyjfh00003968qycsq3ld:baz',
-				timestamp: '2021-03-04T21:00:00.000Z',
-				snapshot: {
-					foo: 1,
-					bar: { '@@type': 'ref', id: 'items/clabgyjfh00003968qycsq3ld:qux' },
-				},
-			},
-		],
-		[
-			{ oid: 'test/what if.boo.blah so what:fajsdfj' },
-			{ oid: 'test/what if:fajsdfj' },
-		],
-	])(
-		'should replace legacy OIDs in a JSON string with new OIDs',
-		(from, to) => {
-			expect(replaceLegacyOidsInObject(from), JSON.stringify(from)).toEqual(to);
-		},
-	);
-});

package/src/oids.ts

@@ -29,10 +29,7 @@ import { isObject, assert } from './utils.js';
 
 export type ObjectIdentifier = string;
 
-export const LEGACY_OID_KEY = '__@@oid_do_not_use';
-export const OID_KEY = '@@id';
-
-const COLLECTION_SEPARATOR = '/';
+const SEGMENT_SEPARATOR = '/';
 const RANDOM_SEPARATOR = ':';
 
 /**
@@ -54,7 +51,7 @@ export function maybeGetOid(obj: any): ObjectIdentifier | undefined {
 	if (!isObject(obj)) {
 		return undefined;
 	}
-	return oidMap.get(obj) ?? obj[OID_KEY] ?? obj[LEGACY_OID_KEY];
+	return oidMap.get(obj);
 }
 
 export function assignOid(obj: any, oid: ObjectIdentifier) {
@@ -78,10 +75,6 @@ export function removeOid(obj: any) {
 	return obj;
 }
 
-export function isOidKey(key: string) {
-	return key === OID_KEY || key === LEGACY_OID_KEY;
-}
-
 /**
  * For sub-objects, assign a random sub-OID if no OID
  * is already assigned.
@@ -141,6 +134,11 @@ function unsanitizeFragment(id: string) {
 		.replace(/˙/g, '.');
 }
 
+/**
+ * Creates an OID for the document with a particular ID.
+ * To create a sub-object OID, use createSubOid and pass
+ * the root OID.
+ */
 export function createOid(
 	collection: string,
 	documentId: string,
@@ -148,7 +146,7 @@ export function createOid(
 ) {
 	let oid =
 		sanitizeFragment(collection) +
-		COLLECTION_SEPARATOR +
+		SEGMENT_SEPARATOR +
 		sanitizeFragment(documentId);
 	if (subId) {
 		oid += RANDOM_SEPARATOR + subId;
@@ -169,18 +167,26 @@ export function decomposeOid(oid: ObjectIdentifier): {
 	id: string;
 	subId?: string;
 } {
-	const [core, random] = oid.split(RANDOM_SEPARATOR);
-	let [collection, idOrLegacyPathId, ...others] = core.split('/');
-	// if there's more than one slash... something went wrong, but we can just bolt the rest on.
+	let [collection, coreId, ...others] = oid.split('/');
+	// if 'others' exists, something's off, but maybe we can recover...
+	// by assuming the last segment is the authz and bolting the rest onto coreId
 	if (others.length) {
-		idOrLegacyPathId += '/' + others.join('/');
+		console.error(
+			`OID ${oid} has more than 3 segments. Attempting to parse it anyway.`,
+		);
+		coreId += '/' + others.join('/');
 	}
+
+	const [idOrLegacyPathId, random] = coreId.split(RANDOM_SEPARATOR);
+
 	let id;
+	// legacy path handling. shouldn't be necessary anymore.
 	if (idOrLegacyPathId.includes('.')) {
 		id = idOrLegacyPathId.slice(0, idOrLegacyPathId.indexOf('.'));
 	} else {
 		id = idOrLegacyPathId;
 	}
+
 	return {
 		collection: unsanitizeFragment(collection),
 		id: unsanitizeFragment(id),
@@ -230,84 +236,6 @@ export function assignOidsToAllSubObjects(
 	}
 }
 
-export function assignOidProperty(obj: any, oid: ObjectIdentifier) {
-	assert(
-		isObject(obj),
-		`Only objects can be assigned OIDs, received ${JSON.stringify(obj)}`,
-	);
-	obj[OID_KEY] = oid;
-	return obj;
-}
-
-export function maybeGetOidProperty(obj: any) {
-	if (!isObject(obj)) {
-		return undefined;
-	}
-	return obj[OID_KEY] || obj[LEGACY_OID_KEY];
-}
-
-function removeOidProperty(obj: any) {
-	if (!isObject(obj)) {
-		return obj;
-	}
-	delete obj[LEGACY_OID_KEY];
-	delete obj[OID_KEY];
-	return obj;
-}
-
-function transferOidFromSystemToProperty(obj: any) {
-	const oid = maybeGetOid(obj);
-	if (oid) {
-		assignOidProperty(obj, oid);
-	}
-}
-
-/**
- * Assigns a special property to all objects in the given object
- * which have an OID
- */
-export function assignOidPropertiesToAllSubObjects(obj: any) {
-	transferOidFromSystemToProperty(obj);
-
-	if (Array.isArray(obj)) {
-		for (let i = 0; i < obj.length; i++) {
-			assignOidPropertiesToAllSubObjects(obj[i]);
-		}
-	} else if (isObject(obj)) {
-		for (const key of Object.keys(obj)) {
-			assignOidPropertiesToAllSubObjects(obj[key]);
-		}
-	}
-}
-
-function copyOidFromPropertyToSystem(obj: any) {
-	const oid = maybeGetOidProperty(obj);
-	if (oid) {
-		assignOid(obj, oid);
-	}
-}
-
-/**
- *
- * Removes the special property from all objects in the given object
- * which have an OID, transferring the OID from the property to the OID
- * system in-memory.
- */
-export function removeOidPropertiesFromAllSubObjects(obj: any) {
-	copyOidFromPropertyToSystem(obj);
-	removeOidProperty(obj);
-
-	if (Array.isArray(obj)) {
-		for (let i = 0; i < obj.length; i++) {
-			removeOidPropertiesFromAllSubObjects(obj[i]);
-		}
-	} else if (isObject(obj)) {
-		for (const key of Object.keys(obj)) {
-			removeOidPropertiesFromAllSubObjects(obj[key]);
-		}
-	}
-}
-
 export function removeOidsFromAllSubObjects(obj: any) {
 	removeOid(obj);
 
@@ -442,10 +370,6 @@ export function getOidSubIdRange(oid: ObjectIdentifier) {
 	const lastSubId = createSubOid(root, () => '\uffff');
 	return [`${root}${RANDOM_SEPARATOR}`, lastSubId];
 }
-export function getLegacyDotOidSubIdRange(oid: ObjectIdentifier) {
-	const root = getOidRoot(oid);
-	return [`${root}.`, `${root}.\uffff`];
-}
 
 export function getRoots(oids: ObjectIdentifier[]) {
 	const set = new Set<ObjectIdentifier>();
@@ -459,6 +383,10 @@ export function areOidsRelated(oidA: ObjectIdentifier, oidB: ObjectIdentifier) {
 	return getOidRoot(oidA) === getOidRoot(oidB);
 }
 
+export function isRootOid(oid: ObjectIdentifier) {
+	return !oid.includes(RANDOM_SEPARATOR);
+}
+
 /**
  * Recursively rewrites any OIDs in an object which are 'foreign' -
  * i.e. relate to some other object/entity - to be local to the
@@ -493,29 +421,3 @@ function migrateForeignOid(parentOid: ObjectIdentifier, child: any) {
 		);
 	}
 }
-
-export function isLegacyDotOid(oid: ObjectIdentifier) {
-	const partBeforeRandomSep = oid.split(RANDOM_SEPARATOR)[0];
-	return partBeforeRandomSep.includes('.');
-}
-
-export function convertLegacyOid(oid: ObjectIdentifier) {
-	const { collection, id, subId } = decomposeOid(oid);
-	return createOid(collection, id, subId);
-}
-
-export const MATCH_LEGACY_OID_JSON_STRING = /"\w+\/[^"]+?(\.[^"]+)+\:[\S]+?"/g;
-export function replaceLegacyOidsInJsonString(string: string) {
-	// replace every match of a legacy OID, converting to a new OID
-	return string.replaceAll(MATCH_LEGACY_OID_JSON_STRING, (match) => {
-		const legacyOid = match.slice(1, match.length - 1);
-		return `"${convertLegacyOid(legacyOid)}"`;
-	});
-}
-export function replaceLegacyOidsInObject(obj: any) {
-	return JSON.parse(replaceLegacyOidsInJsonString(JSON.stringify(obj)));
-}
-
-export function isRootOid(oid: ObjectIdentifier) {
-	return !oid.includes(RANDOM_SEPARATOR);
-}