実行環境¶

Lambda上のアプリケーションは、pocket.toml（または pocket.runtime.toml）とAWSリソースから設定情報を取得します。

pocket.runtime.toml が存在する場合はそちらが優先されます。pocket runtime-config コマンドでビルド専用設定を除外したランタイム用 TOML を生成できます（設定ファイル - pocket runtime-config を参照）。

uv add 'magic-pocket[django]>=X.Y.Z'   # CLI と同じ版に揃える

POCKET_STAGE¶

POCKET_STAGE は Lambda ランタイムでの実行ステージ判定 に使われる環境変数です。 CloudFormation が Lambda 関数の環境変数として自動設定するため、通常はユーザーが手動で設定する必要はありません。

各フレームワークのユーティリティ関数（Django の set_envs() や Rust の set_envs()）は、この変数の有無でローカル環境と Lambda 環境を判別します。POCKET_STAGE が未設定の場合、AWS リソースへのアクセスはスキップされます。

セットされる環境変数¶

set_envs() は、Django・Rust いずれの実装でも、以下の環境変数をセットします。

SPA トークン認証¶

CloudFront 配信の SPA にログイン必須機能を追加する場合、SPA トークン認証モジュールを使用します。 HMAC-SHA256 トークンを Cookie にセットし、CloudFront Function で検証します。

Python (Django)¶

from pocket.django.spa_auth import generate_token, verify_token, spa_login, spa_logout

# トークン生成（ログイン時）
token = generate_token("user123")  # デフォルト有効期限: 7日

# トークン検証（任意のバックエンド処理で）
user_id = verify_token(token)  # 有効なら user_id、無効なら None

ログイン・ログアウトでは、Django の View でレスポンスに Cookie をセットします。

from django.http import HttpResponseRedirect
from pocket.django.spa_auth import spa_login, spa_logout

def login_view(request):
    # Django 認証でユーザーを検証後...
    response = HttpResponseRedirect(request.GET.get("next", "/"))
    spa_login(response, str(request.user.id))
    return response

def logout_view(request):
    response = HttpResponseRedirect("/")
    spa_logout(response)
    return response

SpaTokenCookieMiddleware (必須)¶

require_token = true のルートを公開するときは、SpaTokenCookieMiddleware を MIDDLEWARE に追加してください。入れないと無限 redirect ループに 陥ります。

# settings.py
MIDDLEWARE = [
    # ...
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "pocket.django.spa_auth.SpaTokenCookieMiddleware",
    # ...
]

middleware の動作:

• 認証済み response: pocket-spa-token cookie が無い / 期限切れなら spa_login() で発行 (= self-heal)
• 未認証 response: 残存 cookie があれば spa_logout() で削除
• SPA_TOKEN_SECRET 環境変数が未設定の環境 (gating 未 deploy のローカル等) は no-op

なぜ必要か (詳細)¶

Django session のデフォルト寿命 (SESSION_COOKIE_AGE = 14 日) が SPA token の寿命 (DEFAULT_MAX_AGE = 7 日) より長いため、8 日目以降に「session 有り + token 無し」の状態が全ユーザーに発生します。この状態で require_token ルートにアクセスすると:

1. CloudFront Function が token 無を検出 → login_path (/accounts/login/?next=/) に 302
2. ログインページが「既にログイン済み」を検出し、ログイン処理を通さずに next (/) へ 302 (allauth.RedirectAuthenticatedUserMixin や Django 標準 LoginView.redirect_authenticated_user=True の挙動)
3. → 1 へ戻り 無限ループ

middleware が 2 の bounce response 経路で必ず token を補填するため、1 往復 余分に bounce するだけでループが断ち切られます (ユーザーには visible な 追加遷移には見えません)。

拡張 (subclass で sliding refresh や短命 token に対応)¶

SpaTokenCookieMiddleware は次の 2 つの拡張点を持ちます:

例: 残り寿命が半分を切ったら sliding refresh する subclass:

import time
from django.conf import settings
from pocket.django.spa_auth import (
    COOKIE_NAME,
    SpaTokenCookieMiddleware as BaseMiddleware,
)


class SpaTokenCookieMiddleware(BaseMiddleware):
    def _should_issue(self, request):
        if super()._should_issue(request):
            return True
        token = request.COOKIES[COOKIE_NAME]
        remaining = int(token.split(":")[1]) - time.time()
        return remaining < self._max_age() / 2

    def _max_age(self):
        return settings.SPA_TOKEN_MAX_AGE

MIDDLEWARE で指定するパスを subclass 側に差し替えれば、デフォルトの 挙動はそのまま保ちつつ拡張できます。

Rust (Loco)¶

Rust アプリケーションでは pocket-spa-auth crate を使用できます。

use pocket_spa_auth::{generate_token, verify_token, login_cookie_value, logout_cookie_value};

let secret = std::env::var("SPA_TOKEN_SECRET").unwrap();

// トークン生成 (user_id に ':' を含む / secret が不正 hex の場合は Err)
let token = generate_token("user123", &secret, 604800)?;

// トークン検証
if let Some(user_id) = verify_token(&token, &secret) {
    println!("認証成功: {}", user_id);
}

// Cookie 値の生成
let set_cookie = login_cookie_value(&token, 604800);
let delete_cookie = logout_cookie_value();

API リファレンス¶

Python

• secret を省略すると os.environ["SPA_TOKEN_SECRET"] を使用します
• max_age のデフォルトは 604800（7日間）です
• Cookie 名は pocket-spa-token で、HttpOnly, Secure, SameSite=Lax が設定されます