SDK が物理的なドアを開けるとき、バグは描画の乱れでは済みません。それは「施錠されていない建物」を意味します。本稿では、UnlockOS SDK にリリースした一連の変更を紹介します。これらはすべて同じテーマを共有しています。すなわち、システムは不確実なときにはアクセスを拒否しなければならず、かつ事後に「誰が何をしたか」を証明できなければならないということです。
以下に示すパターンは汎用的なものです。エッジ/サーバーレス API、Row Level Security を備えた Postgres データベース、サードパーティの決済・メッセージングプロバイダを組み合わせたマルチテナントのプラットフォームであれば、どれにでも適用できます。
1. ステップアップ認証を二重に強制する:API とデータベース
プラットフォーム管理者の権限(有料オプションの付与、feature flag のオーバーライド書き込み、テナントへのなりすまし)は、王国の鍵そのものです。パスワード 1 つでは不十分であり、私たちは AAL2 ——第 2 要素を完了した認証済みセッション——を要求します。
決定的な設計判断は、このチェックをミドルウェアに一度だけ実装するのではない、という点です。エッジ関数と RLS ポリシーの両方に実装することで、ルートの実装漏れや PostREST への直接呼び出しによる迂回を防ぎます。
export class ForbiddenError extends Error {
constructor(public readonly code: 'PLATFORM_ADMIN_REQUIRED' | 'AAL2_REQUIRED') {
super(code);
}
}
export interface SessionClaims {
sub: string;
app_role?: string;
aal?: 'aal1' | 'aal2';
}
export function assertPlatformAdmin(
claims: SessionClaims,
): asserts claims is SessionClaims & { app_role: 'platform_admin'; aal: 'aal2' } {
if (claims.app_role !== 'platform_admin') throw new ForbiddenError('PLATFORM_ADMIN_REQUIRED');
if (claims.aal !== 'aal2') throw new ForbiddenError('AAL2_REQUIRED');
}同じ述語を SQL 側にも置き、特権テーブルを守るすべてのポリシーから再利用します。
create or replace function app.is_platform_admin()
returns boolean
language sql
stable
as $$
select coalesce(auth.jwt() ->> 'app_role', '') = 'platform_admin'
and coalesce(auth.jwt() ->> 'aal', 'aal1') = 'aal2';
$$;
create policy platform_admin_writes_overrides
on public.feature_flag_overrides
for all
to authenticated
using (app.is_platform_admin())
with check (app.is_platform_admin());TypeScript の asserts シグネチャに注目してください。assertPlatformAdmin を呼んだ後、コンパイラはそのクレームが特権を持つことを理解します。認可がコメントではなく型フローの一部になるのです。
ハンドラだけでなくポリシーもテストしましょう。 私たちは実際の Postgres インスタンスに対して RLS のアサーションを実行する統合ジョブを追加しました。モックしたクライアントによるユニットテストでは、データベースが実際に何を受け入れるのかを何も証明できないからです。
2. 表示名ではなく安定したキーで認可する
繰り返し現れる権限バグの典型が、人間可読な名前でロールを解決するコードです。
// ❌ names are editable, localized, duplicated per tenant, and sometimes typo'd
const role = await db.roles.findFirst({ where: { name: 'Owner' } });
// ✅ role_key is immutable, unique and part of the schema contract
const OWNER_ROLE_KEY = 'facility_owner' as const;
const role = await db.roles.findFirstOrThrow({ where: { roleKey: OWNER_ROLE_KEY } });管理者が "Owner" を「オーナー」に改名すれば、名前ベースの検索は例外を投げるか、さらに悪いことに別テナントの行にマッチします。私たちは権限レベルの解決とメニュー制御から名前ベースの分岐をすべて排除し、unique (organization_id, role_key) を強制するマイグレーションで裏付けました。
一般化できるルールはこうです。認可判断に使う識別子は、不透明(opaque)で、不変で、union 型として列挙可能でなければならない。
export const ROLE_KEYS = ['platform_admin', 'org_owner', 'facility_owner', 'staff', 'guest'] as const;
export type RoleKey = (typeof ROLE_KEYS)[number];
export const ROLE_LEVEL: Record<RoleKey, number> = {
platform_admin: 100,
org_owner: 80,
facility_owner: 60,
staff: 40,
guest: 10,
};網羅的な Record<RoleKey, number> により、union にロールを追加するとレベルを定義するまでビルドが壊れます。コンパイラがレビュアーになるわけです。
3. Feature flag は fail closed でなければならない
Feature flag は、設定されたアクセス時間外にドアを開けてよいかどうかを含め、現実の挙動を制御します。危険なデフォルトは「フラグのサービスがエラーになったらゲートは開いているものとして扱う」という設計です。
export async function canBypassAccessHours(ctx: EvaluationContext): Promise<boolean> {
try {
return await flags.isEnabled('access_hours_bypass', ctx);
} catch (error) {
logger.error('flag_read_failed', { flag: 'access_hours_bypass', error });
return false; // closed is the only safe answer for a physical lock
}
}オーバーライドの仕組みには、さらに 2 つのルールを適用しました。
- オーバーライドは固定され文書化された優先順位で解決されます:
facility → organization → global default。同じリゾルバがエッジ関数と管理 UI の両方で動くため、運用者はランタイムが見ているものと全く同じものを見ることになります。 - 未知の書き込みポリシーは拒否します。 オーバーライド行が現在のコードで認識できないポリシー文字列を持っていた場合、黙って緩いデフォルトに丸めるのではなく、書き込みを拒否します。
const WRITE_POLICIES = ['platform_admin_only'] as const;
type WritePolicy = (typeof WRITE_POLICIES)[number];
function parseWritePolicy(value: string): WritePolicy {
if (!(WRITE_POLICIES as readonly string[]).includes(value)) {
throw new ForbiddenError('PLATFORM_ADMIN_REQUIRED');
}
return value as WritePolicy;
}4. テーブルレベルでの最小権限
RLS ポリシーは強力ですが、最初に問うべきはこうです。そもそもこのクライアントロールに書き込み権限は必要なのか? フォームのフィールド定義のような設定テーブルは、管理 API を通じて運用者が書き込み、ゲストクライアントは読むだけです。
revoke insert, update, delete on public.form_fields from authenticated, anon;
create policy form_fields_read_published
on public.form_fields
for select
to authenticated, anon
using (exists (
select 1 from public.forms f
where f.id = form_fields.form_id
and f.status = 'published'
));権限の revoke はポリシー式よりも粗く、そして間違えにくい手段です。これを外側のレイヤーとして使い、残る行レベルの細かな条件にポリシーを使いましょう。
5. クリックジャッキング:全面許可ではなく allowlist
ゲスト向けのチェックインアプリは本人確認書類や解錠操作を扱うため、攻撃者が悪意ある iframe に埋め込むことは現実的な脅威です。私たちは自社のマーケティング面を除き、クロスオリジンのフレーム埋め込みを拒否します。
const FRAME_ANCESTORS = ['https://unlockos.io', 'https://st.unlockos.io'];
export function securityHeaders(): Headers {
const headers = new Headers();
headers.set('Content-Security-Policy', [
`frame-ancestors 'self' ${FRAME_ANCESTORS.join(' ')}`,
"base-uri 'self'",
"form-action 'self'",
].join('; '));
headers.set('X-Content-Type-Options', 'nosniff');
headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
return headers;
}さらに、ヘッダーのミドルウェアがデプロイされたバンドルの実際のエントリーポイントであり続けていることを検証する CI ガードも追加しました。文字列の接尾辞ではなく解決済みパスを比較しています。ファイルを移動するリファクタリングは、黙ってヘッダーを落とすのではなく、ビルドを失敗させるべきだからです。
6. 決済ステート:リダイレクトではなく、常にプロバイダへ収束させる
Webhook が必ず届く保証はなく、ブラウザのリダイレクトは攻撃者に操作されうるものです。したがって決済のステートマシンは 3 つの性質を満たさなければなりません。単一の信頼できる情報源(PSP)、冪等な遷移、そしてインフラ自体の設定が不正なときの明示的な incomplete ステートです。
export type PaymentState = 'pending' | 'authorized' | 'captured' | 'failed' | 'incomplete';
const ALLOWED: Record<PaymentState, readonly PaymentState[]> = {
pending: ['authorized', 'captured', 'failed', 'incomplete'],
authorized: ['captured', 'failed'],
captured: [],
failed: [],
incomplete: ['captured', 'failed'],
};
export function canTransition(from: PaymentState, to: PaymentState): boolean {
return ALLOWED[from].includes(to);
}
export async function reconcile(intentId: string, trigger: 'webhook' | 'return'): Promise<PaymentRow> {
const remote = await psp.retrieveIntent(intentId);
return db.transaction(async (tx) => {
const row = await tx.payments.selectForUpdate(intentId);
const next = mapProviderStatus(remote.status);
if (row.state === next) return row;
if (!canTransition(row.state, next)) {
logger.warn('illegal_payment_transition', { intentId, from: row.state, to: next, trigger });
return row;
}
const updated = await tx.payments.update(intentId, { state: next, settledBy: trigger });
await tx.auditLogs.insert({ type: 'payment.state_changed', subjectId: intentId, from: row.state, to: next });
return updated;
});
}selectForUpdate と「同一ステートなら no-op」の組み合わせにより、webhook とリターン URL の経路が競合しても安全になります。先に到着した方が勝ち、負けた方は安価な read で終わります。同じ照合関数が両方のトリガーを処理するため、監査すべきコードパスは 1 つだけです。
また別途、本番決済が有効化されているにもかかわらず webhook エンドポイントが登録されていない組織は、管理画面上で incomplete として可視化され、プラットフォームチームに通知されるようになりました。静かな劣化こそが敵であり、見える壊れ方は機能です。
7. ライフサイクルのガードは UI ではなくドメインに置く
施設は pre_opening → open → closed と遷移します。予約、ウォークインのチェックイン、レッスン申込、ロッカーの買い取り——複数の独立したエントリーポイントが、いずれも「この施設は新しいコミットメントを受け付けてよいか?」という同じ問いへの答えを必要とします。各画面で条件を複製すれば、必ず食い違いが生じます。
export type FacilityStatus = 'pre_opening' | 'open' | 'closed';
export class DomainError extends Error {
constructor(public readonly code: 'FACILITY_PREOPENING' | 'FACILITY_CLOSED' | 'CONFIG_DEACTIVATED') {
super(code);
}
}
export function assertAcceptsNewCommitments(facility: { status: FacilityStatus }): void {
switch (facility.status) {
case 'open':
return;
case 'pre_opening':
throw new DomainError('FACILITY_PREOPENING');
case 'closed':
throw new DomainError('FACILITY_CLOSED');
}
}union に対して default を持たない switch は意図的なものです。ステータスを追加すると、新しいケースを処理するまで型検査に失敗します。そして各ガードは安定したマシンコードを返し、SDK がそれをローカライズされたメッセージへマッピングします。
const MESSAGES: Record<DomainError['code'], { ja: string; en: string }> = {
FACILITY_PREOPENING: { ja: 'この施設は準備中です。', en: 'This facility is not open yet.' },
FACILITY_CLOSED: { ja: 'この施設は閉鎖されています。', en: 'This facility is closed.' },
CONFIG_DEACTIVATED: { ja: 'この設定は無効化されています。', en: 'This configuration is deactivated.' },
};クライアントはコードでマッチし、人間はメッセージを読みます。エラー文をクライアントに文字列マッチさせてはいけません。
同じルールが下流の 2 つのバグも捕まえました。承認後に閉鎖された施設に対して継続課金を行ってはならないこと、そして無効化されたにもかかわらず id で参照され続けている予約設定に対してロッカーを開けたり買い取りを受け付けたりしてはならないことです。論理削除済み・無効化済みのレコードも id では到達可能です。読み取り経路は存在だけでなくステータスを確認しなければなりません。
8. 完全性と最小権限を両立する監査ログ
監査証跡が信頼を得るには、3 つの条件が必要です。特権操作が記録されていること、閲覧者が権限のある範囲しか見られないこと、そして出力が理解可能であることです。
私たちはカタログを拡張し、ロールの付与と剥奪、API キーの発行・失効・再有効化をカバーしました。まさに攻撃者が永続化(persistence)のために使う操作です。
export const AUDIT_EVENTS = {
'role.granted': { group: 'access_control', severity: 'high' },
'role.revoked': { group: 'access_control', severity: 'high' },
'api_key.issued': { group: 'credentials', severity: 'high' },
'api_key.revoked': { group: 'credentials', severity: 'high' },
'api_key.reactivated': { group: 'credentials', severity: 'high' },
'payment.state_changed': { group: 'billing', severity: 'info' },
} as const;
export type AuditEventType = keyof typeof AUDIT_EVENTS;
export type AuditEventGroup = (typeof AUDIT_EVENTS)[AuditEventType]['group'];フィルタリングはサーバー側へ移しました。全件取得した結果をクライアント側でフィルタすると、閲覧者が見てはいけないイベントの存在や形が漏れ、さらにページネーションも壊れます。
select id, occurred_at, event_type, actor_id, subject_id, metadata
from public.audit_logs
where organization_id = $1
and event_type = any($2::text[])
and occurred_at >= $3
order by occurred_at desc
limit $4 offset $5;許可される event_type の配列は、サーバー側で呼び出し元のロールから導出されます。リクエストの値をそのまま受け取ることは決してありません。最後に、UI は内部のイベントキーではなくカタログのラベルを表示します。誰にも読めない監査ログは証拠にはなりません。
9. 腐らないテスト
私たちが修正した 2 件の失敗は、プロダクトのバグではなく 時間に依存したフィクスチャ が原因でした。絶対日付で未来を指定した会員予約はやがて過去になり、キャンセル経路は書き込み時に実時計に対して再検証していたため、固定したシード日付が黙ってテスト対象の分岐を変えてしまっていたのです。
// ❌ passes today, fails next quarter
const checkIn = new Date('2026-01-10T15:00:00+09:00');
// ✅ expresses the intent: a booking that is still in the future
const checkIn = addDays(startOfToday(), 30);
// ✅ or freeze the clock when the assertion is about the clock itself
vi.useFakeTimers().setSystemTime(new Date('2026-01-10T15:00:00+09:00'));経験則として、テストが now() を読む遷移を検証するなら、日付を now() からの相対で表現するか、now() 自体を制御するかのどちらかにします。中途半端に両方を混ぜてはいけません。不安定なセキュリティテストはいずれ無効化され、無効化されたテストは何も守りません。
また、重めの認可シナリオは CI 上の専用 Postgres 統合ジョブへ移しました。ポリシー、トリガー、制約はコードです。ハンドラと同じだけのカバレッジを受けるに値します。
まとめ
| パターン | なぜ信頼を得られるのか |
|---|---|
| AAL2 を API と RLS の両方でチェック | ルートの実装漏れがステップアップ認証を迂回できない |
名前ではなく role_key で認可 |
ロールの改名やローカライズで権限昇格が起きない |
| エラー時にフラグは fail closed | インフラ障害がドアを開けることはない |
| 権限を revoke してからポリシーを書く | 外側は粗い最小権限、内側は細粒度 |
frame-ancestors の allowlist |
ゲストの解錠フローがクリックジャックされない |
| 決済はプロバイダから照合する | リダイレクトや未達の webhook がステートを偽装できない |
| ライフサイクルをドメイン層でガード | 「この施設は利用可能か?」への答えが全エントリーポイントで 1 つ |
| 型付き監査カタログ + サーバー側フィルタ | 完全な証拠と、最小権限の読み取り |
| テストでは相対日時か凍結した時計 | セキュリティテストが正しい理由でグリーンであり続ける |
どれも気の利いた技ではありません。それこそが要点です。物理的なアクセスを制御するシステムにおいては、正しいデフォルトとは退屈で、2 つのレイヤーで重複していて、規律ではなく型チェッカーとデータベースによって強制されるものなのです。