@uptime.app/contracts 3.0.45-rc.0 → 3.0.46

package/src/access-control/hack-access-control.ts

@@ -1,32 +1,32 @@
-export interface HackAccessControl {
-    id: string;
-    hackId: string; // PK
-    // do I need baseLocaleHackId ? don't think I do
-    v: number;
-    acl: string[]
-    createdAt: string;
-    updatedAt: string;
-    /** added April 2025 and backfilled */
-    owner: string;
-    tenant: string;
-}
-
-export interface HackAccessControlCreatedEvent {
-    id: string;
-    type: 'HackAccessControlCreated';
-    payload: HackAccessControl;
-}
-
-export interface HackAccessControlUpdatedEvent {
-    id: string;
-    type: 'HackAccessControlUpdated';
-    payload: HackAccessControl;
-}
-
-export interface HackAccessControlDeletedEvent {
-    id: string;
-    type: 'HackAccessControlDeleted';
-    payload: HackAccessControl;
-}
-
-export type HackAccessControlChangedEvent = HackAccessControlCreatedEvent | HackAccessControlUpdatedEvent | HackAccessControlDeletedEvent;
+export interface HackAccessControl {
+    id: string;
+    hackId: string; // PK
+    // do I need baseLocaleHackId ? don't think I do
+    v: number;
+    acl: string[]
+    createdAt: string;
+    updatedAt: string;
+    /** added April 2025 and backfilled */
+    owner: string;
+    tenant: string;
+}
+
+export interface HackAccessControlCreatedEvent {
+    id: string;
+    type: 'HackAccessControlCreated';
+    payload: HackAccessControl;
+}
+
+export interface HackAccessControlUpdatedEvent {
+    id: string;
+    type: 'HackAccessControlUpdated';
+    payload: HackAccessControl;
+}
+
+export interface HackAccessControlDeletedEvent {
+    id: string;
+    type: 'HackAccessControlDeleted';
+    payload: HackAccessControl;
+}
+
+export type HackAccessControlChangedEvent = HackAccessControlCreatedEvent | HackAccessControlUpdatedEvent | HackAccessControlDeletedEvent;

package/src/access-control/profile-access-control.ts

@@ -1,28 +1,28 @@
-export interface ProfileAccessControl {
-    id: string;
-    profileId: string;
-    v: number;
-    acl: string[]
-    createdAt: string;
-    updatedAt: string;
-}
-
-export interface ProfileAccessControlCreatedEvent {
-    id: string;
-    type: 'ProfileAccessControlCreated';
-    payload: ProfileAccessControl;
-}
-
-export interface ProfileAccessControlUpdatedEvent {
-    id: string;
-    type: 'ProfileAccessControlUpdated';
-    payload: ProfileAccessControl;
-}
-
-export interface ProfileAccessControlDeletedEvent {
-    id: string;
-    type: 'ProfileAccessControlDeleted';
-    payload: ProfileAccessControl;
-}
-
+export interface ProfileAccessControl {
+    id: string;
+    profileId: string;
+    v: number;
+    acl: string[]
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface ProfileAccessControlCreatedEvent {
+    id: string;
+    type: 'ProfileAccessControlCreated';
+    payload: ProfileAccessControl;
+}
+
+export interface ProfileAccessControlUpdatedEvent {
+    id: string;
+    type: 'ProfileAccessControlUpdated';
+    payload: ProfileAccessControl;
+}
+
+export interface ProfileAccessControlDeletedEvent {
+    id: string;
+    type: 'ProfileAccessControlDeleted';
+    payload: ProfileAccessControl;
+}
+
 export type ProfileAccessControlChangedEvent = ProfileAccessControlCreatedEvent | ProfileAccessControlUpdatedEvent | ProfileAccessControlDeletedEvent;

package/src/acl/acl-utils.test.ts

@@ -0,0 +1,272 @@
+import { parseAclEntry, getAclValuesByNamespace, aclFor, AclBuilder } from './acl-utils';
+
+describe('parseAclEntry', () => {
+
+    test('returns null for empty string', () => {
+        expect(parseAclEntry('')).toBeNull();
+    });
+
+    test('returns null for whitespace-only string', () => {
+        expect(parseAclEntry('   ')).toBeNull();
+    });
+
+    test('parses a simple namespace-only entry', () => {
+        expect(parseAclEntry('public')).toEqual({
+            raw: 'public',
+            excluded: false,
+            namespace: 'public',
+            value: null
+        });
+    });
+
+    test('parses a namespace:value entry', () => {
+        expect(parseAclEntry('catalogue:uptime')).toEqual({
+            raw: 'catalogue:uptime',
+            excluded: false,
+            namespace: 'catalogue',
+            value: 'uptime'
+        });
+    });
+
+    test('parses an excluded namespace-only entry', () => {
+        expect(parseAclEntry('!public')).toEqual({
+            raw: '!public',
+            excluded: true,
+            namespace: 'public',
+            value: null
+        });
+    });
+
+    test('parses an excluded namespace:value entry', () => {
+        expect(parseAclEntry('!catalogue:uptime')).toEqual({
+            raw: '!catalogue:uptime',
+            excluded: true,
+            namespace: 'catalogue',
+            value: 'uptime'
+        });
+    });
+
+    test('trims leading and trailing whitespace', () => {
+        expect(parseAclEntry('  catalogue:uptime  ')).toEqual({
+            raw: 'catalogue:uptime',
+            excluded: false,
+            namespace: 'catalogue',
+            value: 'uptime'
+        });
+    });
+
+    test('returns null when namespace is empty (entry starts with colon)', () => {
+        expect(parseAclEntry(':value')).toBeNull();
+    });
+
+    test('preserves colons in value', () => {
+        expect(parseAclEntry('catalogue:b2b:org-123')).toEqual({
+            raw: 'catalogue:b2b:org-123',
+            excluded: false,
+            namespace: 'catalogue',
+            value: 'b2b:org-123'
+        });
+    });
+});
+
+describe('getAclValuesByNamespace', () => {
+    const acl = [
+        'public',
+        'catalogue:uptime',
+        'catalogue:premium',
+        '!catalogue:restricted',
+        'b2b:org-1',
+        '!b2b:org-2',
+        'user:user-123'
+    ];
+
+    test('returns included values for a namespace by default', () => {
+        expect(getAclValuesByNamespace(acl, 'catalogue')).toEqual(['uptime', 'premium']);
+    });
+
+    test('returns excluded values when mode is "excluded"', () => {
+        expect(getAclValuesByNamespace(acl, 'catalogue', { mode: 'excluded' })).toEqual(['restricted']);
+    });
+
+    test('returns all values when mode is "all"', () => {
+        expect(getAclValuesByNamespace(acl, 'catalogue', { mode: 'all' })).toEqual(['uptime', 'premium', 'restricted']);
+    });
+
+    test('returns empty array when namespace has no matches', () => {
+        expect(getAclValuesByNamespace(acl, 'subject')).toEqual([]);
+    });
+
+    test('deduplicates values by default', () => {
+        const aclWithDupes = ['catalogue:uptime', 'catalogue:uptime', 'catalogue:premium'];
+        expect(getAclValuesByNamespace(aclWithDupes, 'catalogue')).toEqual(['uptime', 'premium']);
+    });
+
+    test('preserves duplicates when dedupe is false', () => {
+        const aclWithDupes = ['catalogue:uptime', 'catalogue:uptime', 'catalogue:premium'];
+        expect(getAclValuesByNamespace(aclWithDupes, 'catalogue', { dedupe: false })).toEqual(['uptime', 'uptime', 'premium']);
+    });
+
+    test('excludes namespace-only entries (no value)', () => {
+        expect(getAclValuesByNamespace(acl, 'public')).toEqual([]);
+    });
+
+    test('returns empty array for empty acl', () => {
+        expect(getAclValuesByNamespace([], 'catalogue')).toEqual([]);
+    });
+
+    test('skips invalid entries', () => {
+        const aclWithInvalid = ['', '   ', 'catalogue:uptime'];
+        expect(getAclValuesByNamespace(aclWithInvalid, 'catalogue')).toEqual(['uptime']);
+    });
+});
+
+describe('AclBuilder', () => {
+    test('includes "public" by default', () => {
+        const acl = new AclBuilder().build();
+        expect(acl).toContain('public');
+    });
+
+    test('excludes "public" when includePublic is false', () => {
+        const acl = new AclBuilder({ includePublic: false }).build();
+        expect(acl).not.toContain('public');
+    });
+
+    test('includes user entry when includeUser is specified', () => {
+        const acl = new AclBuilder({ includeUser: 'user-123' }).build();
+        expect(acl).toContain('user:user-123');
+    });
+
+    test('merges baseAcl entries', () => {
+        const acl = new AclBuilder({ baseAcl: ['catalogue:uptime', '!catalogue:restricted'] }).build();
+        expect(acl).toContain('catalogue:uptime');
+        expect(acl).toContain('!catalogue:restricted');
+    });
+
+    describe('allow', () => {
+        test('adds namespace:value entry', () => {
+            const acl = new AclBuilder({ includePublic: false }).allow('catalogue', 'uptime').build();
+            expect(acl).toContain('catalogue:uptime');
+        });
+
+        test('adds namespace-only entry when no value provided', () => {
+            const acl = new AclBuilder({ includePublic: false }).allow('public').build();
+            expect(acl).toContain('public');
+        });
+
+        test('removes entry from excluded when allowed', () => {
+            const acl = new AclBuilder({ includePublic: false })
+                .deny('catalogue', 'uptime')
+                .allow('catalogue', 'uptime')
+                .build();
+            expect(acl).toContain('catalogue:uptime');
+            expect(acl).not.toContain('!catalogue:uptime');
+        });
+    });
+
+    describe('deny', () => {
+        test('adds excluded namespace:value entry', () => {
+            const acl = new AclBuilder().deny('catalogue', 'restricted').build();
+            expect(acl).toContain('!catalogue:restricted');
+        });
+
+        test('removes entry from included when denied', () => {
+            const acl = new AclBuilder({ includePublic: false })
+                .allow('catalogue', 'uptime')
+                .deny('catalogue', 'uptime')
+                .build();
+            expect(acl).not.toContain('catalogue:uptime');
+            expect(acl).toContain('!catalogue:uptime');
+        });
+    });
+
+    describe('allowCatalogue', () => {
+        test('adds catalogue:<id> entry', () => {
+            const acl = new AclBuilder().allowCatalogue('premium').build();
+            expect(acl).toContain('catalogue:premium');
+        });
+    });
+
+    describe('denyCatalogue', () => {
+        test('adds !catalogue:<id> entry', () => {
+            const acl = new AclBuilder().denyCatalogue('restricted').build();
+            expect(acl).toContain('!catalogue:restricted');
+        });
+    });
+
+    describe('allowOrganisation', () => {
+        test('adds b2b:<id> entry', () => {
+            const acl = new AclBuilder().allowOrganisation('org-1').build();
+            expect(acl).toContain('b2b:org-1');
+        });
+    });
+
+    describe('denySubject', () => {
+        test('adds !subject:<value> entry', () => {
+            const acl = new AclBuilder().denySubject('some-topic').build();
+            expect(acl).toContain('!subject:some-topic');
+        });
+    });
+
+    describe('addRaw', () => {
+        test('adds an included raw entry', () => {
+            const acl = new AclBuilder({ includePublic: false }).addRaw('catalogue:uptime').build();
+            expect(acl).toContain('catalogue:uptime');
+        });
+
+        test('adds an excluded raw entry', () => {
+            const acl = new AclBuilder({ includePublic: false }).addRaw('!catalogue:restricted').build();
+            expect(acl).toContain('!catalogue:restricted');
+        });
+
+        test('ignores invalid raw entries', () => {
+            const acl = new AclBuilder({ includePublic: false }).addRaw('').build();
+            expect(acl).toEqual([]);
+        });
+    });
+
+    describe('addMany', () => {
+        test('adds multiple entries at once', () => {
+            const acl = new AclBuilder({ includePublic: false })
+                .addMany(['catalogue:uptime', 'b2b:org-1', '!catalogue:restricted'])
+                .build();
+            expect(acl).toContain('catalogue:uptime');
+            expect(acl).toContain('b2b:org-1');
+            expect(acl).toContain('!catalogue:restricted');
+        });
+    });
+});
+
+describe('aclFor', () => {
+    test('includes user entry', () => {
+        const acl = aclFor({ userId: 'user-abc', organisationIds: [], catalogueIds: [] });
+        expect(acl).toContain('user:user-abc');
+    });
+
+    test('always includes catalogue:uptime', () => {
+        const acl = aclFor({ userId: 'user-abc', organisationIds: [], catalogueIds: [] });
+        expect(acl).toContain('catalogue:uptime');
+    });
+
+    test('includes provided catalogue ids', () => {
+        const acl = aclFor({ userId: 'user-abc', organisationIds: [], catalogueIds: ['premium', 'free'] });
+        expect(acl).toContain('catalogue:premium');
+        expect(acl).toContain('catalogue:free');
+    });
+
+    test('includes b2b catalogue entry for each organisation', () => {
+        const acl = aclFor({ userId: 'user-abc', organisationIds: ['org-1', 'org-2'], catalogueIds: [] });
+        expect(acl).toContain('catalogue:b2b:org-1');
+        expect(acl).toContain('catalogue:b2b:org-2');
+    });
+
+    test('includes b2b namespace entry for each organisation', () => {
+        const acl = aclFor({ userId: 'user-abc', organisationIds: ['org-1', 'org-2'], catalogueIds: [] });
+        expect(acl).toContain('b2b:org-1');
+        expect(acl).toContain('b2b:org-2');
+    });
+
+    test('includes public by default', () => {
+        const acl = aclFor({ userId: 'user-abc', organisationIds: [], catalogueIds: [] });
+        expect(acl).toContain('public');
+    });
+});

package/src/acl/acl-utils.ts

@@ -0,0 +1,179 @@
+export type AclQueryMode = 'included' | 'excluded' | 'all';
+
+export interface ParsedAclEntry {
+    raw: string;
+    excluded: boolean;
+    namespace: string;
+    value: string | null;
+}
+
+export interface GetAclValuesOptions {
+    mode?: AclQueryMode;
+    dedupe?: boolean;
+}
+
+export interface BuildAclOptions {
+    includePublic?: boolean;
+    includeUser?: string;
+    baseAcl?: string[];
+}
+
+function normalizeAclEntry(entry: string): string {
+    return entry.trim();
+}
+
+export function parseAclEntry(entry: string): ParsedAclEntry | null {
+    const raw = normalizeAclEntry(entry);
+    if (!raw) {
+        return null;
+    }
+
+    const excluded = raw.startsWith('!');
+    const token = excluded ? raw.slice(1) : raw;
+    const firstColonIndex = token.indexOf(':');
+
+    if (firstColonIndex === -1) {
+        return {
+            raw,
+            excluded,
+            namespace: token,
+            value: null
+        };
+    }
+
+    const namespace = token.slice(0, firstColonIndex);
+    const value = token.slice(firstColonIndex + 1);
+
+    if (!namespace) {
+        return null;
+    }
+
+    return {
+        raw,
+        excluded,
+        namespace,
+        value
+    };
+}
+
+export function getAclValuesByNamespace(
+    acl: string[],
+    namespace: string,
+    options: GetAclValuesOptions = {}
+): string[] {
+    const mode = options.mode ?? 'included';
+    const dedupe = options.dedupe ?? true;
+
+    const values = acl
+        .map(parseAclEntry)
+        .filter((entry): entry is ParsedAclEntry => Boolean(entry))
+        .filter(entry => entry.namespace === namespace)
+        .filter(entry => entry.value !== null)
+        .filter(entry => {
+            if (mode === 'all') {
+                return true;
+            }
+            if (mode === 'included') {
+                return !entry.excluded;
+            }
+            return entry.excluded;
+        })
+        .map(entry => entry.value as string);
+
+    return dedupe ? Array.from(new Set(values)) : values;
+}
+
+export function aclFor({ userId, organisationIds, catalogueIds }: { userId: string; organisationIds: string[]; catalogueIds: string[] }) {
+    const builder = new AclBuilder({ includeUser: userId });
+
+    // everyone has access to the uptime catalogue
+    builder.allowCatalogue('uptime');
+
+    catalogueIds.forEach(catalogueId => builder.allowCatalogue(catalogueId));
+
+    // each b2b has a catalogue called b2b:<organisationId> so permit access to this
+    organisationIds.forEach(organisationId => builder.allowCatalogue(`b2b:${organisationId}`));
+
+    // previously we also had acl of b2b:<organisationId> that is still being used for collections
+    organisationIds.forEach(organisationId => builder.allowOrganisation(organisationId));
+
+    return builder.build();
+}
+
+export class AclBuilder {
+    private included = new Set<string>();
+    private excluded = new Set<string>();
+
+    constructor(options: BuildAclOptions = {}) {
+        const includePublic = options.includePublic ?? true;
+
+        if (includePublic) {
+            this.included.add('public');
+        }
+
+        if (options.includeUser) {
+            this.included.add(`user:${options.includeUser}`);
+        }
+
+        if (options.baseAcl?.length) {
+            this.addMany(options.baseAcl);
+        }
+    }
+
+    addRaw(entry: string): this {
+        const parsed = parseAclEntry(entry);
+        if (!parsed) {
+            return this;
+        }
+
+        if (parsed.excluded) {
+            this.excluded.add(parsed.raw.slice(1));
+        } else {
+            this.included.add(parsed.raw);
+        }
+
+        return this;
+    }
+
+    addMany(entries: string[]): this {
+        entries.forEach(entry => this.addRaw(entry));
+        return this;
+    }
+
+    allow(namespace: string, value?: string): this {
+        const token = value === undefined ? namespace : `${namespace}:${value}`;
+        this.included.add(token);
+        this.excluded.delete(token);
+        return this;
+    }
+
+    deny(namespace: string, value?: string): this {
+        const token = value === undefined ? namespace : `${namespace}:${value}`;
+        this.excluded.add(token);
+        this.included.delete(token);
+        return this;
+    }
+
+    allowCatalogue(catalogueId: string): this {
+        return this.allow('catalogue', catalogueId);
+    }
+
+    denyCatalogue(catalogueId: string): this {
+        return this.deny('catalogue', catalogueId);
+    }
+
+    allowOrganisation(organisationId: string): this {
+        return this.allow('b2b', organisationId);
+    }
+
+    denySubject(subject: string): this {
+        return this.deny('subject', subject);
+    }
+
+    build(): string[] {
+        return [
+            ...this.included,
+            ...Array.from(this.excluded).map(token => `!${token}`)
+        ];
+    }
+}

package/src/app-hack/app-full-hack.ts

@@ -1,9 +1,9 @@
-import { AppRestrictedHack } from './app-restricted-hack';
-import { EnrichedHack } from '../enriched-hack/enriched-hack';
-
-/**
- * Includes all of a hack's content that premium users are allowed to access. Free users should not have access to this object.
- */
-export interface AppFullHack extends AppRestrictedHack {
-    segments: EnrichedHack['segments'];
-}
+import { AppRestrictedHack } from './app-restricted-hack';
+import { EnrichedHack } from '../enriched-hack/enriched-hack';
+
+/**
+ * Includes all of a hack's content that premium users are allowed to access. Free users should not have access to this object.
+ */
+export interface AppFullHack extends AppRestrictedHack {
+    segments: EnrichedHack['segments'];
+}