@oxy.so/core 1.0.0

package/dist/esm/mixins/index.js

@@ -0,0 +1,132 @@
+/**
+ * Centralized mixin exports and composition helper
+ *
+ * This module provides a clean way to compose all mixins
+ * and ensures consistent ordering for better maintainability
+ */
+import { OxyServicesBase } from '../OxyServices.base.js';
+import { OxyServicesAuthMixin } from './OxyServices.auth.js';
+import { OxyServicesUserMixin } from './OxyServices.user.js';
+import { OxyServicesIdentityMixin } from './OxyServices.identity.js';
+import { OxyServicesIdentityBackupMixin } from './OxyServices.identityBackup.js';
+import { OxyServicesPrivacyMixin } from './OxyServices.privacy.js';
+import { OxyServicesLanguageMixin } from './OxyServices.language.js';
+import { OxyServicesPaymentMixin } from './OxyServices.payment.js';
+import { OxyServicesReputationMixin } from './OxyServices.reputation.js';
+import { OxyServicesAssetsMixin } from './OxyServices.assets.js';
+import { OxyServicesAccountsMixin } from './OxyServices.accounts.js';
+import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps.js';
+import { OxyServicesStoreMixin } from './OxyServices.store.js';
+import { OxyServicesLocationMixin } from './OxyServices.location.js';
+import { OxyServicesAnalyticsMixin } from './OxyServices.analytics.js';
+import { OxyServicesDevicesMixin } from './OxyServices.devices.js';
+import { OxyServicesSecurityMixin } from './OxyServices.security.js';
+import { OxyServicesUtilityMixin } from './OxyServices.utility.js';
+import { OxyServicesFeaturesMixin } from './OxyServices.features.js';
+import { OxyServicesTopicsMixin } from './OxyServices.topics.js';
+import { OxyServicesContactsMixin } from './OxyServices.contacts.js';
+import { OxyServicesNotificationsMixin } from './OxyServices.notifications.js';
+import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
+import { OxyServicesCivicMixin } from './OxyServices.civic.js';
+import { OxyServicesChainsMixin } from './OxyServices.chains.js';
+import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
+import { OxyServicesLinksMixin } from './OxyServices.links.js';
+import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph.js';
+import { OxyServicesInferenceMixin } from './OxyServices.inference.js';
+import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer.js';
+/**
+ * Mixin pipeline - applied in order from first to last.
+ *
+ * Order matters for dependencies:
+ * 1. Base auth mixin first (required by all others)
+ * 2. User mixin (requires auth)
+ * 3. Feature mixins (can depend on user)
+ * 4. Utility mixin last (augments all)
+ *
+ * To add a new mixin: insert it at the appropriate position in this array.
+ */
+const MIXIN_PIPELINE = [
+    // Base authentication
+    OxyServicesAuthMixin,
+    // User management (requires auth)
+    OxyServicesUserMixin,
+    // Self-sovereign identity (DID, signed records, auth-method ↔ VM mapping)
+    OxyServicesIdentityMixin,
+    // Encrypted off-device identity backup (b3 Feature 1): store/restore an
+    // encrypted copy of the self-custody key, keyed off the recovery phrase.
+    OxyServicesIdentityBackupMixin,
+    OxyServicesPrivacyMixin,
+    // Feature mixins
+    OxyServicesLanguageMixin,
+    OxyServicesPaymentMixin,
+    OxyServicesReputationMixin,
+    OxyServicesAssetsMixin,
+    // Unified account graph + the applications owned within it. The clean-cut
+    // replacement for the former managedAccounts + workspaces + applications
+    // (account-management) mixins.
+    OxyServicesAccountsMixin,
+    // OAuth-consent surface (public app identity + connected-app grants). Kept
+    // separate from account ownership.
+    OxyServicesConnectedAppsMixin,
+    // The app store: the public storefront, the reviews on it, and the listing a
+    // publisher edits. A module OVER the platform — turn it off and OAuth still
+    // works — so it is its own surface rather than more of `accounts`.
+    OxyServicesStoreMixin,
+    OxyServicesLocationMixin,
+    OxyServicesAnalyticsMixin,
+    OxyServicesDevicesMixin,
+    OxyServicesSecurityMixin,
+    OxyServicesFeaturesMixin,
+    OxyServicesTopicsMixin,
+    OxyServicesContactsMixin,
+    // Push-token registration: the one SDK-owned register/unregister pair every
+    // Oxy app uses, and what lets a "Sign in with Oxy" request be delivered to a
+    // known Commons installation instead of falling back to a QR.
+    OxyServicesNotificationsMixin,
+    OxyServicesAppDataMixin,
+    // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
+    OxyServicesCivicMixin,
+    OxyServicesChainsMixin,
+    // User nodes / decentralization (Fase 5): register/read/revoke/manage the
+    // caller's personal data node + ingest hint.
+    OxyServicesNodesMixin,
+    // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
+    // so apps stop scraping link metadata locally.
+    OxyServicesLinksMixin,
+    // The user-owned follow graph (#809). One relationship per user and target,
+    // shared across applications, with per-application context on top.
+    OxyServicesFollowGraphMixin,
+    // The inference model catalogue (#972). Reads only, and deliberately no
+    // request/stream/receipt methods — the public inference edge those would
+    // call is workstream 4 and does not exist yet. See
+    // `docs/inference/README.md` for what is and is not built.
+    OxyServicesInferenceMixin,
+    // Device-first token mint: the client half of the zero-cookie transport
+    // (`mintFromDeviceSecret` → `POST /session/device/token`).
+    OxyServicesDeviceBootMixin,
+    // Device-to-device identity transfer ("add a device"): E2E-encrypted key
+    // clone over a short-lived relay (b3 Feature 2).
+    OxyServicesDeviceTransferMixin,
+    // Utility (last, can use all above)
+    OxyServicesUtilityMixin,
+];
+/**
+ * Composes all OxyServices mixins using a pipeline pattern.
+ *
+ * This is equivalent to the nested calls but more readable and maintainable.
+ * Adding a new mixin: add it to MIXIN_PIPELINE at the appropriate position
+ * AND extend `AllMixinInstances` so its methods are visible to consumers.
+ *
+ * The cast through `unknown` carries the runtime augmentation chain into the
+ * static type system. `Array.reduce` cannot track each mixin's generic
+ * refinement, so we assert the final shape exposed by all mixins together.
+ *
+ * @returns The fully composed OxyServices constructor with all mixins applied
+ */
+export function composeOxyServices() {
+    const composed = MIXIN_PIPELINE.reduce((Base, mixin) => mixin(Base), OxyServicesBase);
+    return composed;
+}
+// Export the pipeline for testing/debugging
+export { MIXIN_PIPELINE };

package/dist/esm/mixins/mixinHelpers.js

@@ -0,0 +1,48 @@
+/**
+ * Helper utilities for mixin classes
+ * Provides common patterns to reduce code duplication
+ */
+/**
+ * Wraps an async method with standard error handling
+ * Reduces boilerplate in mixin methods
+ */
+export async function withErrorHandling(operation, handleError) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw handleError(error);
+    }
+}
+/**
+ * Creates a standard API request method with error handling
+ * Reduces duplication across mixin methods
+ */
+export function createApiMethod(makeRequest, handleError, method, url, options = {}) {
+    return async (...args) => {
+        const urlString = typeof url === 'function' ? url(...args) : url;
+        const requestData = options.transformData ? options.transformData(args) : args[0];
+        const requestOptions = {
+            cache: options.cache ?? true,
+            cacheTTL: options.cacheTTL,
+            retry: options.retry ?? true,
+        };
+        try {
+            const response = await makeRequest(method, urlString, requestData, requestOptions);
+            return options.transformResponse ? options.transformResponse(response) : response;
+        }
+        catch (error) {
+            throw handleError(error);
+        }
+    };
+}
+/**
+ * Cache time constants (in milliseconds)
+ */
+export const CACHE_TIMES = {
+    SHORT: 1 * 60 * 1000, // 1 minute
+    MEDIUM: 2 * 60 * 1000, // 2 minutes
+    LONG: 5 * 60 * 1000, // 5 minutes
+    VERY_LONG: 10 * 60 * 1000, // 10 minutes
+    EXTRA_LONG: 30 * 60 * 1000, // 30 minutes
+};

package/dist/esm/models/Topic.js

@@ -0,0 +1,13 @@
+export var TopicType;
+(function (TopicType) {
+    TopicType["CATEGORY"] = "category";
+    TopicType["TOPIC"] = "topic";
+    TopicType["ENTITY"] = "entity";
+})(TopicType || (TopicType = {}));
+export var TopicSource;
+(function (TopicSource) {
+    TopicSource["SEED"] = "seed";
+    TopicSource["AI"] = "ai";
+    TopicSource["MANUAL"] = "manual";
+    TopicSource["SYSTEM"] = "system";
+})(TopicSource || (TopicSource = {}));

package/dist/esm/models/interfaces.js

@@ -0,0 +1,17 @@
+/**
+ * Security event severity mapping (single source of truth)
+ * Maps each event type to its default severity level
+ */
+export const SECURITY_EVENT_SEVERITY_MAP = {
+    'sign_in': 'low',
+    'sign_out': 'low',
+    'profile_updated': 'low',
+    'email_changed': 'medium',
+    'device_added': 'medium',
+    'device_removed': 'medium',
+    'security_settings_changed': 'medium',
+    'account_recovery': 'high',
+    'private_key_exported': 'high',
+    'backup_created': 'high',
+    'suspicious_activity': 'critical',
+};

package/dist/esm/models/session.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/server/auth.js

@@ -0,0 +1,154 @@
+import { OXY_SERVICE_ENVIRONMENTS } from '../utils/oxyServiceEnvironment.js';
+export { OXY_SERVICE_ENVIRONMENTS };
+function normalizeId(value) {
+    const normalized = value?.trim();
+    return normalized && normalized.length > 0 ? normalized : null;
+}
+function ensureUser(req, userId) {
+    const existing = req.user;
+    if (existing) {
+        const user = {
+            ...existing,
+            id: normalizeId(existing.id) ?? normalizeId(existing._id) ?? userId,
+        };
+        req.user = user;
+        return user;
+    }
+    const user = { id: userId };
+    req.user = user;
+    return user;
+}
+export function getOxyUserId(req) {
+    const authReq = req;
+    return (normalizeId(authReq.userId) ??
+        normalizeId(authReq.user?.id) ??
+        normalizeId(authReq.user?._id));
+}
+export function isOxyAuthenticated(req) {
+    return getOxyUserId(req) !== null;
+}
+/**
+ * The billing principal of a request, or `null` when the request carries no
+ * verified service principal (an ordinary user session is not a billable
+ * machine principal — its account is resolved from the account graph, not from
+ * a token claim).
+ *
+ * Reads `req.serviceApp` and NOTHING else: not `req.userId`, not `req.user`,
+ * not `req.serviceActingAs`. That exclusivity is the invariant this function
+ * exists to hold, and `serviceTokenAttribution.test.ts` mutation-tests it.
+ *
+ * **It answers for the SERVICE-TOKEN lane only.** The API's machine-credential
+ * lane (`oxy_sk_*`, issue #972 §2.3) resolves the same five facts into its own
+ * `req.machineCredential`, deliberately never `req.serviceApp` — populating the
+ * latter would hand a self-serve third-party credential the lane that only
+ * platform-trusted applications may enter. So a machine-credential request has
+ * no billing principal HERE and resolves `null`, which fails closed: the caller
+ * must handle it, and `getRequiredOxyBillingPrincipal` throws rather than
+ * charging anyone. One accessor answering for both lanes belongs to the public
+ * inference edge that has to admit both, and it needs the machine principal's
+ * shape to move into this package first.
+ */
+export function getOxyBillingPrincipal(req) {
+    const serviceApp = req.serviceApp;
+    if (!serviceApp) {
+        return null;
+    }
+    const accountId = normalizeId(serviceApp.ownerAccountId);
+    const applicationId = normalizeId(serviceApp.appId);
+    const credentialId = normalizeId(serviceApp.credentialId);
+    if (!accountId || !applicationId || !credentialId) {
+        return null;
+    }
+    return {
+        accountId,
+        applicationId,
+        credentialId,
+        environment: serviceApp.environment,
+        scopes: serviceApp.scopes,
+    };
+}
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+export function getRequiredOxyBillingPrincipal(req) {
+    const principal = getOxyBillingPrincipal(req);
+    if (!principal) {
+        throw new Error('Request has no verified Oxy service principal');
+    }
+    return principal;
+}
+/**
+ * The delegated end user of a service request, or `null`.
+ *
+ * Deliberately reads `req.serviceActingAs` — the grant-verified delegation —
+ * and not `req.userId`, which on a non-service request is the caller's own
+ * session identity and is not a delegation at all.
+ */
+export function getOxyDelegatedUserId(req) {
+    return normalizeId(req.serviceActingAs?.userId);
+}
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+export function getOxyRequestAttribution(req) {
+    const principal = getOxyBillingPrincipal(req);
+    if (!principal) {
+        return null;
+    }
+    return { ...principal, delegatedUserId: getOxyDelegatedUserId(req) };
+}
+export function getRequiredOxyUserId(req) {
+    const userId = getOxyUserId(req);
+    if (!userId) {
+        throw new Error('User not authenticated');
+    }
+    return userId;
+}
+export function requireOxyAuth(req, res, next) {
+    const userId = getOxyUserId(req);
+    if (!userId) {
+        res.status(401).json({
+            error: 'Unauthorized',
+            message: 'Authentication required',
+        });
+        return;
+    }
+    const authReq = req;
+    authReq.userId = userId;
+    ensureUser(authReq, userId);
+    next();
+}
+export function createOptionalOxyAuth(oxy, options = {}) {
+    const resolveSession = oxy.auth({ ...options.auth, optional: true });
+    return (req, res, next) => {
+        if (getOxyUserId(req)) {
+            next();
+            return;
+        }
+        resolveSession(req, res, (error) => {
+            if (error) {
+                next(error);
+                return;
+            }
+            next();
+        });
+    };
+}
+export function createOxyAuthMiddleware(oxy, options = {}) {
+    const resolveSession = createOptionalOxyAuth(oxy, options);
+    return (req, res, next) => {
+        if (getOxyUserId(req)) {
+            requireOxyAuth(req, res, next);
+            return;
+        }
+        resolveSession(req, res, (error) => {
+            if (error) {
+                next(error);
+                return;
+            }
+            requireOxyAuth(req, res, next);
+        });
+    };
+}

package/dist/esm/server/capabilityTicket.js

@@ -0,0 +1,183 @@
+import { randomUUID, sign as signBytes, verify as verifyBytes, } from 'node:crypto';
+import { capabilityTicketClaimsSchema, } from '@oxy.so/contracts';
+const ALGORITHM = 'EdDSA';
+const TOKEN_TYPE = 'OXY-CAPABILITY+JWT';
+const DEFAULT_MAX_TTL_SECONDS = 300;
+export class CapabilityTicketError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CapabilityTicketError';
+    }
+}
+function base64UrlEncode(value) {
+    return Buffer.from(value).toString('base64url');
+}
+function decodeJsonSegment(segment) {
+    try {
+        return JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new CapabilityTicketError('malformed', 'Capability ticket is not valid base64url JSON');
+    }
+}
+function valuesAtPath(input, path) {
+    let current = [input];
+    for (const segment of path.split('.')) {
+        const next = [];
+        for (const value of current) {
+            const records = Array.isArray(value) ? value : [value];
+            for (const record of records) {
+                if (typeof record !== 'object' || record === null || Array.isArray(record))
+                    continue;
+                if (Object.prototype.hasOwnProperty.call(record, segment)) {
+                    next.push(record[segment]);
+                }
+            }
+        }
+        if (next.length === 0)
+            return [];
+        current = next;
+    }
+    return current.flatMap((value) => Array.isArray(value) ? value : [value]);
+}
+/** Enforces the signed per-action bounds before a domain handler runs. */
+export function inputSatisfiesCapabilityLimits(tool, input, limits) {
+    for (const limit of limits) {
+        if (limit.tool !== tool)
+            return false;
+        const actualValues = valuesAtPath(input, limit.key);
+        if (actualValues.length === 0)
+            return false;
+        if (typeof limit.value === 'number') {
+            const maximum = limit.value;
+            if (!actualValues.every((actual) => (typeof actual === 'number' && Number.isFinite(actual) && actual <= maximum)))
+                return false;
+            continue;
+        }
+        if (!actualValues.every((actual) => actual === limit.value))
+            return false;
+    }
+    return true;
+}
+export function issueCapabilityTicket(claims, options) {
+    const ttlSeconds = options.ttlSeconds ?? 60;
+    if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > DEFAULT_MAX_TTL_SECONDS) {
+        throw new CapabilityTicketError('ttl_exceeded', `Capability ticket TTL must be between 1 and ${DEFAULT_MAX_TTL_SECONDS} seconds`);
+    }
+    const issuedAt = Math.floor((options.now ?? new Date()).getTime() / 1000);
+    const payload = capabilityTicketClaimsSchema.parse({
+        ...claims,
+        iss: options.issuer,
+        iat: issuedAt,
+        exp: issuedAt + ttlSeconds,
+        jti: options.jti ?? randomUUID(),
+    });
+    if (options.privateKey.asymmetricKeyType !== 'ed25519') {
+        throw new CapabilityTicketError('invalid_claims', 'Capability tickets require an Ed25519 private key');
+    }
+    const header = { alg: ALGORITHM, typ: TOKEN_TYPE, kid: options.keyId };
+    const signingInput = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(payload))}`;
+    return `${signingInput}.${base64UrlEncode(signBytes(null, Buffer.from(signingInput), options.privateKey))}`;
+}
+export function verifyCapabilityTicket(token, options) {
+    const segments = token.split('.');
+    if (segments.length !== 3) {
+        throw new CapabilityTicketError('malformed', 'Capability ticket must have three segments');
+    }
+    const [encodedHeader, encodedPayload, encodedSignature] = segments;
+    if (!encodedHeader || !encodedPayload || !encodedSignature) {
+        throw new CapabilityTicketError('malformed', 'Capability ticket contains an empty segment');
+    }
+    const header = decodeJsonSegment(encodedHeader);
+    if (typeof header !== 'object' || header === null || Array.isArray(header)) {
+        throw new CapabilityTicketError('malformed', 'Capability ticket header is not supported');
+    }
+    const headerRecord = header;
+    if (Object.keys(headerRecord).length !== 3
+        || headerRecord.alg !== ALGORITHM
+        || headerRecord.typ !== TOKEN_TYPE
+        || typeof headerRecord.kid !== 'string'
+        || headerRecord.kid.length === 0) {
+        throw new CapabilityTicketError('malformed', 'Capability ticket header is not supported');
+    }
+    const publicKey = options.resolvePublicKey(headerRecord.kid);
+    if (!publicKey || publicKey.asymmetricKeyType !== 'ed25519') {
+        throw new CapabilityTicketError('unknown_key', 'Capability ticket signing key is not trusted');
+    }
+    let providedSignature;
+    try {
+        providedSignature = Buffer.from(encodedSignature, 'base64url');
+    }
+    catch {
+        throw new CapabilityTicketError('malformed', 'Capability ticket signature is malformed');
+    }
+    if (!verifyBytes(null, Buffer.from(`${encodedHeader}.${encodedPayload}`), publicKey, providedSignature)) {
+        throw new CapabilityTicketError('invalid_signature', 'Capability ticket signature is invalid');
+    }
+    const parsed = capabilityTicketClaimsSchema.safeParse(decodeJsonSegment(encodedPayload));
+    if (!parsed.success) {
+        throw new CapabilityTicketError('invalid_claims', 'Capability ticket claims are invalid');
+    }
+    const claims = parsed.data;
+    const now = Math.floor((options.now ?? new Date()).getTime() / 1000);
+    if (claims.iat > now + 5) {
+        throw new CapabilityTicketError('not_yet_valid', 'Capability ticket is not yet valid');
+    }
+    if (claims.exp <= now) {
+        throw new CapabilityTicketError('expired', 'Capability ticket has expired');
+    }
+    if (claims.exp - claims.iat > (options.maximumTtlSeconds ?? DEFAULT_MAX_TTL_SECONDS)) {
+        throw new CapabilityTicketError('ttl_exceeded', 'Capability ticket lifetime exceeds the accepted maximum');
+    }
+    if (claims.aud !== options.audience) {
+        throw new CapabilityTicketError('wrong_audience', 'Capability ticket audience does not match this app');
+    }
+    if (options.issuer && claims.iss !== options.issuer) {
+        throw new CapabilityTicketError('wrong_issuer', 'Capability ticket issuer is not trusted');
+    }
+    return claims;
+}
+export function readCapabilityAuthorization(authorization) {
+    if (!authorization)
+        return null;
+    const [scheme, token, extra] = authorization.trim().split(/\s+/);
+    if (scheme?.toLowerCase() !== 'capability' || !token || extra)
+        return null;
+    return token;
+}
+/**
+ * Verifies cryptographic scope first, then asks the authority service for a
+ * live decision. This second check is what makes revocation effective between
+ * planning and execution.
+ */
+export function createCapabilityTicketMiddleware(options) {
+    return async (request, response, next) => {
+        const token = readCapabilityAuthorization(request.header('authorization'));
+        if (!token) {
+            response.status(401).json({ error: 'capability_ticket_required' });
+            return;
+        }
+        let claims;
+        try {
+            claims = verifyCapabilityTicket(token, options);
+        }
+        catch (error) {
+            const code = error instanceof CapabilityTicketError ? error.code : 'invalid_claims';
+            response.status(401).json({ error: 'invalid_capability_ticket', code });
+            return;
+        }
+        try {
+            const decision = await options.authorize(claims);
+            if (!decision.allowed) {
+                response.status(403).json({ error: 'capability_denied', reason: decision.reason });
+                return;
+            }
+            request.capabilityTicket = claims;
+            next();
+        }
+        catch {
+            response.status(503).json({ error: 'capability_authority_unavailable' });
+        }
+    };
+}