@rangka/core 0.0.1

package/src/auth/debug.ts

@@ -0,0 +1,157 @@
+import type { DatabaseClient } from '../db/client.js';
+import type { PermissionRegistry } from './permission-registry.js';
+import type { SchemaRegistry } from '../schema/registry.js';
+
+export interface DebugResult {
+  user: { email: string; id: string; enabled: boolean };
+  roles: string[];
+  inheritanceChains: Record<string, string[]>;
+  effectivePermissions: Record<string, Record<string, boolean>>;
+  fieldRestrictions: Record<string, { hidden: string[]; readOnly: string[] }>;
+}
+
+const TRACKED_ACTIONS = ['read', 'write', 'create', 'delete'] as const;
+
+// Looks up a user by email and resolves their full permission picture:
+// roles, inheritance chains, effective model permissions, and field restrictions.
+export async function debugPermissions(
+  email: string,
+  db: DatabaseClient,
+  permissionRegistry: PermissionRegistry,
+  _schemaRegistry: SchemaRegistry,
+): Promise<DebugResult> {
+  const user = await findUserByEmail(db, email);
+  const roleNames = await getUserRoleNames(db, user.id);
+  const resolved = permissionRegistry.resolvePermissionsForRoles(roleNames);
+
+  return {
+    user: { email: user.email, id: user.id, enabled: user.enabled },
+    roles: roleNames,
+    inheritanceChains: buildInheritanceChains(roleNames, permissionRegistry),
+    effectivePermissions: buildEffectivePermissions(resolved),
+    fieldRestrictions: buildFieldRestrictions(resolved),
+  };
+}
+
+async function findUserByEmail(db: DatabaseClient, email: string) {
+  const user = (await db
+    .selectFrom('core.user')
+    .selectAll()
+    .where('email', '=', email)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    .executeTakeFirst()) as any;
+
+  if (!user) throw new Error(`User not found: ${email}`);
+  return user;
+}
+
+async function getUserRoleNames(db: DatabaseClient, userId: string): Promise<string[]> {
+  const userRoles = await db
+    .selectFrom('core.user_role')
+    .selectAll()
+    .where('user_id', '=', userId)
+    .execute();
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const roleIds = userRoles.map((ur: any) => ur.role_id);
+  if (roleIds.length === 0) return [];
+
+  const roles = await db.selectFrom('core.role').selectAll().where('id', 'in', roleIds).execute();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return roles.map((r: any) => r.name);
+}
+
+function buildInheritanceChains(
+  roleNames: string[],
+  permissionRegistry: PermissionRegistry,
+): Record<string, string[]> {
+  const chains: Record<string, string[]> = {};
+  for (const name of roleNames) {
+    chains[name] = permissionRegistry.getInheritanceChain(name);
+  }
+  return chains;
+}
+
+function buildEffectivePermissions(
+  resolved: ReturnType<PermissionRegistry['resolvePermissionsForRoles']>,
+): Record<string, Record<string, boolean>> {
+  const permissions: Record<string, Record<string, boolean>> = {};
+
+  for (const [model, modelPerms] of Object.entries(resolved.models)) {
+    const granted: Record<string, boolean> = {};
+    for (const action of TRACKED_ACTIONS) {
+      if (modelPerms[action]) granted[action] = true;
+    }
+    permissions[model] = granted;
+  }
+
+  return permissions;
+}
+
+function buildFieldRestrictions(
+  resolved: ReturnType<PermissionRegistry['resolvePermissionsForRoles']>,
+): Record<string, { hidden: string[]; readOnly: string[] }> {
+  const restrictions: Record<string, { hidden: string[]; readOnly: string[] }> = {};
+
+  for (const [model, modelPerms] of Object.entries(resolved.models)) {
+    if (!modelPerms.fieldPermissions) continue;
+
+    const hidden: string[] = [];
+    const readOnly: string[] = [];
+
+    for (const [field, fieldPerm] of Object.entries(modelPerms.fieldPermissions)) {
+      if (fieldPerm.read === false) hidden.push(field);
+      else if (fieldPerm.write === false) readOnly.push(field);
+    }
+
+    if (hidden.length > 0 || readOnly.length > 0) {
+      restrictions[model] = { hidden, readOnly };
+    }
+  }
+
+  return restrictions;
+}
+
+export function formatDebugResult(result: DebugResult): string {
+  const lines: string[] = [];
+
+  lines.push(`User: ${result.user.email} (${result.user.id})`);
+  lines.push(`Enabled: ${result.user.enabled}`);
+  lines.push(`Roles: ${result.roles.join(', ') || '(none)'}`);
+  lines.push('');
+
+  if (Object.keys(result.inheritanceChains).length > 0) {
+    lines.push('Role Inheritance:');
+    for (const [role, chain] of Object.entries(result.inheritanceChains)) {
+      if (chain.length > 0) {
+        lines.push(`  ${role} ← ${chain.join(' ← ')}`);
+      } else {
+        lines.push(`  ${role} (no inheritance)`);
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push('Effective Permissions:');
+  for (const [model, perms] of Object.entries(result.effectivePermissions)) {
+    const actions = Object.entries(perms)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    lines.push(`  ${model}: ${actions.join(', ') || '(none)'}`);
+  }
+  lines.push('');
+
+  if (Object.keys(result.fieldRestrictions).length > 0) {
+    lines.push('Field Restrictions:');
+    for (const [model, restrictions] of Object.entries(result.fieldRestrictions)) {
+      if (restrictions.hidden.length > 0) {
+        lines.push(`  ${model} [hidden]: ${restrictions.hidden.join(', ')}`);
+      }
+      if (restrictions.readOnly.length > 0) {
+        lines.push(`  ${model} [read-only]: ${restrictions.readOnly.join(', ')}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/auth/field-permissions.ts

@@ -0,0 +1,116 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { ResolvedModel } from '../schema/types.js';
+import type { ModelPermissions } from '@rangka/shared';
+import { getAuthContext } from './session.js';
+import { ForbiddenError } from '../errors.js';
+
+export interface ResolvedFieldPermissions {
+  hidden: Set<string>;
+  readOnly: Set<string>;
+}
+
+// Determines which fields should be hidden or read-only for a given model
+// based on the user's resolved permissions.
+export function resolveFieldPermissions(
+  model: ResolvedModel,
+  modelPermissionsMap: Record<string, ModelPermissions>,
+): ResolvedFieldPermissions {
+  const hidden = new Set<string>();
+  const readOnly = new Set<string>();
+
+  const permissions = modelPermissionsMap[model.qualifiedName];
+  if (!permissions?.fieldPermissions) {
+    return { hidden, readOnly };
+  }
+
+  for (const [field, fieldPerm] of Object.entries(permissions.fieldPermissions)) {
+    if (fieldPerm.read === false) {
+      hidden.add(field);
+    } else if (fieldPerm.write === false) {
+      readOnly.add(field);
+    }
+  }
+
+  return { hidden, readOnly };
+}
+
+// Hook that rejects writes to read-only fields with a 403 response.
+export function createFieldWriteGuard(model: ResolvedModel) {
+  return async function fieldWriteGuard(
+    request: FastifyRequest,
+    _reply: FastifyReply,
+  ): Promise<void> {
+    if (!isWriteMethod(request.method)) return;
+
+    const ctx = getAuthContext(request);
+    if (!ctx.permissions) return;
+
+    const { readOnly } = resolveFieldPermissions(model, ctx.permissions.models);
+    if (readOnly.size === 0) return;
+
+    const body = request.body as Record<string, unknown> | undefined;
+    if (!body) return;
+
+    const violatedFields = Object.keys(body).filter((field) => readOnly.has(field));
+
+    if (violatedFields.length > 0) {
+      throw new ForbiddenError(
+        'FORBIDDEN',
+        `Cannot write to read-only fields: ${violatedFields.join(', ')}`,
+        { fields: violatedFields },
+      );
+    }
+  };
+}
+
+// Hook that strips hidden fields from response payloads before sending.
+export function createFieldStripHook(model: ResolvedModel) {
+  return async function fieldStripHook(
+    request: FastifyRequest,
+    _reply: FastifyReply,
+    payload: unknown,
+  ): Promise<unknown> {
+    if (typeof payload !== 'string') return payload;
+
+    const ctx = getAuthContext(request);
+    if (!ctx.permissions) return payload;
+
+    const { hidden } = resolveFieldPermissions(model, ctx.permissions.models);
+    if (hidden.size === 0) return payload;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let parsed: any;
+    try {
+      parsed = JSON.parse(payload);
+    } catch {
+      return payload;
+    }
+
+    if (Array.isArray(parsed?.data)) {
+      parsed.data = parsed.data.map((record: Record<string, unknown>) =>
+        stripFields(record, hidden),
+      );
+    } else if (typeof parsed?.data === 'object' && parsed.data !== null) {
+      parsed.data = stripFields(parsed.data, hidden);
+    }
+
+    return JSON.stringify(parsed);
+  };
+}
+
+function isWriteMethod(method: string): boolean {
+  return method === 'POST' || method === 'PUT' || method === 'PATCH';
+}
+
+function stripFields(
+  record: Record<string, unknown>,
+  hidden: Set<string>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (!hidden.has(key)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/src/auth/index.ts

@@ -0,0 +1,37 @@
+export { hashPassword, verifyPassword } from './password.js';
+export {
+  PermissionRegistry,
+  DuplicateRoleError,
+  RoleInheritanceCycleError,
+} from './permission-registry.js';
+export {
+  createAuthHook,
+  getAuthContext,
+  createSessionHandler,
+  deleteSessionHandler,
+  regenerateSessionToken,
+  generateToken,
+} from './session.js';
+export { createModelPermissionGuard, isOwnerOnly, modelHasCreatedBy } from './model-permissions.js';
+export { createScopeHook, createScopeWriteGuard, applyScopeFiltersToQuery } from './scopes.js';
+export type { ScopeHookContext, FilterProvider } from './scopes.js';
+export { ScopeRegistry, ScopeResolutionError } from './scope-registry.js';
+export type { ResolvedScope, ModelScopeBinding } from './scope-registry.js';
+export {
+  createFieldWriteGuard,
+  createFieldStripHook,
+  resolveFieldPermissions,
+} from './field-permissions.js';
+export { debugPermissions, formatDebugResult } from './debug.js';
+export { getCoreModels, getCoreApp } from './core-module.js';
+export { coreSchemas } from './core-models.js';
+export { seedCoreData } from './seed.js';
+export type {
+  AuthUser,
+  AuthSession,
+  RequestContext,
+  ScopeFilter,
+  ResolvedPermissions,
+  RegisteredRole,
+  PermissionCacheEntry,
+} from './types.js';

package/src/auth/model-permissions.ts

@@ -0,0 +1,59 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { ResolvedModel } from '../schema/types.js';
+import type { PermissionRegistry } from './permission-registry.js';
+import type { ResolvedPermissions } from './types.js';
+import { getAuthContext } from './session.js';
+import { ForbiddenError } from '../errors.js';
+
+type PermAction = 'read' | 'write' | 'create' | 'delete';
+
+export function isOwnerOnly(
+  permissions: ResolvedPermissions | undefined,
+  model: string,
+  action: 'read' | 'write' | 'delete',
+): boolean {
+  if (!permissions) return false;
+  const modelPerms = permissions.models[model];
+  return modelPerms?.[action] === 'own';
+}
+
+export function modelHasCreatedBy(model: ResolvedModel): boolean {
+  return model.fields.some((f) => f.name === 'created_by');
+}
+
+const METHOD_TO_ACTION: Record<string, PermAction> = {
+  GET: 'read',
+  POST: 'create',
+  PUT: 'write',
+  PATCH: 'write',
+  DELETE: 'delete',
+};
+
+function resolveAction(method: string): PermAction {
+  return METHOD_TO_ACTION[method] ?? 'read';
+}
+
+export function createModelPermissionGuard(
+  model: ResolvedModel,
+  _permissionRegistry: PermissionRegistry,
+) {
+  return async function modelPermissionGuard(
+    request: FastifyRequest,
+    _reply: FastifyReply,
+  ): Promise<void> {
+    const ctx = getAuthContext(request);
+    if (!ctx.permissions) {
+      throw new ForbiddenError('FORBIDDEN', 'No permissions resolved');
+    }
+
+    const action = resolveAction(request.method);
+    const modelPerms = ctx.permissions.models[model.qualifiedName];
+
+    if (!modelPerms || !modelPerms[action]) {
+      throw new ForbiddenError(
+        'FORBIDDEN',
+        `Insufficient permission: ${action} on ${model.qualifiedName}`,
+      );
+    }
+  };
+}

package/src/auth/password.ts

@@ -0,0 +1,22 @@
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+
+const SALT_LENGTH = 32;
+const KEY_LENGTH = 64;
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+
+export function hashPassword(password: string): string {
+  const salt = randomBytes(SALT_LENGTH);
+  const hash = scryptSync(password, salt, KEY_LENGTH, SCRYPT_PARAMS);
+  return `${salt.toString('hex')}:${hash.toString('hex')}`;
+}
+
+export function verifyPassword(password: string, stored: string): boolean {
+  const [saltHex, hashHex] = stored.split(':');
+  if (!saltHex || !hashHex) return false;
+
+  const salt = Buffer.from(saltHex, 'hex');
+  const storedHash = Buffer.from(hashHex, 'hex');
+  const computedHash = scryptSync(password, salt, KEY_LENGTH, SCRYPT_PARAMS);
+
+  return timingSafeEqual(storedHash, computedHash);
+}

package/src/auth/permission-registry.ts

@@ -0,0 +1,171 @@
+import type { RolesConfig, RoleConfig, ModelPermissions } from '@rangka/shared';
+import type { RegisteredRole, ResolvedPermissions } from './types.js';
+
+const MODEL_ACTIONS = ['read', 'write', 'create', 'delete'] as const;
+
+export class PermissionRegistry {
+  private readonly roles: Map<string, RegisteredRole> = new Map();
+  private resolvedInheritance: Map<string, string[]> = new Map();
+  private version: number = 0;
+
+  registerRoles(config: RolesConfig, app: string): void {
+    for (const [name, roleConfig] of Object.entries(config)) {
+      if (this.roles.has(name)) {
+        const existing = this.roles.get(name)!;
+        throw new DuplicateRoleError(name, existing.app, app);
+      }
+      this.roles.set(name, { name, config: roleConfig, app });
+    }
+    this.rebuildInheritanceChains();
+    this.version++;
+  }
+
+  getRole(name: string): RegisteredRole | undefined {
+    return this.roles.get(name);
+  }
+
+  getAllRoles(): RegisteredRole[] {
+    return Array.from(this.roles.values());
+  }
+
+  getVersion(): number {
+    return this.version;
+  }
+
+  getInheritanceChain(roleName: string): string[] {
+    return this.resolvedInheritance.get(roleName) ?? [];
+  }
+
+  // Collects permissions from the given roles (and their ancestors) into a single resolved set.
+  // Later roles in the array can only grant — they never revoke what an earlier role granted.
+  resolvePermissionsForRoles(roleNames: string[]): ResolvedPermissions {
+    const models: Record<string, ModelPermissions> = {};
+    const pages = new Set<string>();
+
+    for (const roleName of roleNames) {
+      const rolesToApply = [...this.getInheritanceChain(roleName), roleName];
+
+      for (const name of rolesToApply) {
+        const role = this.roles.get(name);
+        if (!role) continue;
+
+        this.applyModelPermissions(role.config, models);
+        this.collectPages(role.config, pages);
+      }
+    }
+
+    return { models, pages: Array.from(pages), version: this.version };
+  }
+
+  private applyModelPermissions(
+    roleConfig: RoleConfig,
+    target: Record<string, ModelPermissions>,
+  ): void {
+    if (!roleConfig.models) return;
+
+    for (const [model, sourcePerms] of Object.entries(roleConfig.models)) {
+      if (!target[model]) target[model] = {};
+      mergeModelPermissions(target[model], sourcePerms);
+    }
+  }
+
+  private collectPages(roleConfig: RoleConfig, pages: Set<string>): void {
+    if (!roleConfig.pages) return;
+    for (const page of roleConfig.pages) {
+      pages.add(page);
+    }
+  }
+
+  // Walks each role's `extends` chain and caches the full ancestor list.
+  // Detects cycles and missing parents.
+  private rebuildInheritanceChains(): void {
+    const resolved = new Map<string, string[]>();
+    const inProgress = new Set<string>();
+
+    const resolve = (name: string): string[] => {
+      if (resolved.has(name)) return resolved.get(name)!;
+
+      if (inProgress.has(name)) {
+        throw new RoleInheritanceCycleError([...inProgress, name]);
+      }
+
+      inProgress.add(name);
+
+      const role = this.roles.get(name);
+      if (!role?.config.extends) {
+        inProgress.delete(name);
+        resolved.set(name, []);
+        return [];
+      }
+
+      const parentName = role.config.extends;
+      if (!this.roles.has(parentName)) {
+        throw new Error(`Role "${name}" extends unknown role "${parentName}"`);
+      }
+
+      const ancestors = [...resolve(parentName), parentName];
+      inProgress.delete(name);
+      resolved.set(name, ancestors);
+      return ancestors;
+    };
+
+    for (const name of this.roles.keys()) {
+      resolve(name);
+    }
+
+    this.resolvedInheritance = resolved;
+  }
+}
+
+// Merges source permissions into target. true > 'own' > unset/false.
+function mergeModelPermissions(target: ModelPermissions, source: ModelPermissions): void {
+  for (const action of MODEL_ACTIONS) {
+    const src = source[action];
+    if (!src) continue;
+    // true is the most permissive — never downgrade from true to 'own'
+    if (target[action] === true) continue;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    target[action] = src as any;
+  }
+
+  if (!source.fieldPermissions) return;
+
+  if (!target.fieldPermissions) target.fieldPermissions = {};
+
+  for (const [field, sourceField] of Object.entries(source.fieldPermissions)) {
+    const targetField = target.fieldPermissions[field];
+
+    if (!targetField) {
+      target.fieldPermissions[field] = { ...sourceField };
+      continue;
+    }
+
+    // Grants always win; denials only apply if not already granted
+    if (sourceField.read === true) targetField.read = true;
+    else if (sourceField.read === false && targetField.read === undefined) targetField.read = false;
+
+    if (sourceField.write === true) targetField.write = true;
+    else if (sourceField.write === false && targetField.write === undefined)
+      targetField.write = false;
+  }
+}
+
+export class DuplicateRoleError extends Error {
+  constructor(
+    public readonly role: string,
+    public readonly existingApp: string,
+    public readonly newApp: string,
+  ) {
+    super(
+      `Duplicate role "${role}": already registered by "${existingApp}", cannot register from "${newApp}"`,
+    );
+    this.name = 'DuplicateRoleError';
+  }
+}
+
+export class RoleInheritanceCycleError extends Error {
+  constructor(public readonly cycle: string[]) {
+    super(`Role inheritance cycle detected: ${cycle.join(' → ')}`);
+    this.name = 'RoleInheritanceCycleError';
+  }
+}

package/src/auth/scope-filters.ts

@@ -0,0 +1,11 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { ScopeFilter } from './types.js';
+
+export function applyScopeFiltersToQuery(query: any, scopeFilters: ScopeFilter[]): any {
+  let result = query;
+  for (const filter of scopeFilters) {
+    const operator = filter.operator === 'in' ? 'in' : '=';
+    result = result.where(filter.field, operator, filter.value);
+  }
+  return result;
+}

package/src/auth/scope-registry.ts

@@ -0,0 +1,121 @@
+import type { ModuleConfig, ScopeDefinition, ScopeConfig } from '@rangka/shared';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { ResolvedModel } from '../schema/types.js';
+
+export interface ResolvedScope {
+  name: string;
+  definition: ScopeDefinition;
+  module: string;
+}
+
+export interface ModelScopeBinding {
+  scopeName: string;
+  column: string;
+  scopeModel: string;
+}
+
+export class ScopeResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ScopeResolutionError';
+  }
+}
+
+export class ScopeRegistry {
+  private readonly scopes: Map<string, ResolvedScope> = new Map();
+  private readonly modelBindings: Map<string, ModelScopeBinding> = new Map();
+
+  constructor(modules: ModuleConfig[], schemaRegistry: SchemaRegistry) {
+    this.registerScopes(modules);
+    this.resolveModelBindings(schemaRegistry);
+  }
+
+  getScope(name: string): ResolvedScope | undefined {
+    return this.scopes.get(name);
+  }
+
+  getAllScopes(): ResolvedScope[] {
+    return Array.from(this.scopes.values());
+  }
+
+  getModelBinding(qualifiedName: string): ModelScopeBinding | undefined {
+    return this.modelBindings.get(qualifiedName);
+  }
+
+  isModelScoped(qualifiedName: string): boolean {
+    return this.modelBindings.has(qualifiedName);
+  }
+
+  private registerScopes(modules: ModuleConfig[]): void {
+    for (const mod of modules) {
+      if (!mod.scopes) continue;
+      for (const [name, definition] of Object.entries(mod.scopes)) {
+        if (this.scopes.has(name)) {
+          throw new ScopeResolutionError(
+            `Scope "${name}" declared by module "${mod.name}" conflicts with existing scope from module "${this.scopes.get(name)!.module}"`,
+          );
+        }
+        this.scopes.set(name, { name, definition, module: mod.name });
+      }
+    }
+  }
+
+  private resolveModelBindings(schemaRegistry: SchemaRegistry): void {
+    for (const model of schemaRegistry.getAllModels()) {
+      if (!model.scope) continue;
+
+      const binding = this.resolveBinding(model, schemaRegistry);
+      this.modelBindings.set(model.qualifiedName, binding);
+    }
+  }
+
+  private resolveBinding(model: ResolvedModel, schemaRegistry: SchemaRegistry): ModelScopeBinding {
+    const scopeName = this.parseScopeName(model.scope!);
+    const explicitField = this.parseExplicitField(model.scope!);
+
+    const scope = this.scopes.get(scopeName);
+    if (!scope) {
+      throw new ScopeResolutionError(
+        `Model "${model.qualifiedName}" references scope "${scopeName}" which is not defined by any module`,
+      );
+    }
+
+    const column = explicitField ?? this.findLinkColumn(model, scope, schemaRegistry);
+    return { scopeName, column, scopeModel: scope.definition.model };
+  }
+
+  private parseScopeName(scopeConfig: ScopeConfig): string {
+    if (typeof scopeConfig === 'string') return scopeConfig;
+    return scopeConfig.name;
+  }
+
+  private parseExplicitField(scopeConfig: ScopeConfig): string | undefined {
+    if (typeof scopeConfig === 'string') return undefined;
+    return scopeConfig.field;
+  }
+
+  private findLinkColumn(
+    model: ResolvedModel,
+    scope: ResolvedScope,
+    schemaRegistry: SchemaRegistry,
+  ): string {
+    const relationships = schemaRegistry.getRelationshipsForModel(model.qualifiedName);
+    const matchingLinks = relationships.filter(
+      (r) => r.type === 'link' && r.to === scope.definition.model,
+    );
+
+    if (matchingLinks.length === 0) {
+      throw new ScopeResolutionError(
+        `Model "${model.qualifiedName}" is scoped by "${scope.name}" but has no link field to "${scope.definition.model}"`,
+      );
+    }
+
+    if (matchingLinks.length > 1) {
+      throw new ScopeResolutionError(
+        `Model "${model.qualifiedName}" has multiple link fields to "${scope.definition.model}" (${matchingLinks.map((l) => l.field).join(', ')}). Specify which field to use: scope: { name: '${scope.name}', field: '<field_name>' }`,
+      );
+    }
+
+    return matchingLinks[0].field;
+  }
+}