README

Laravel 13 애플리케이션에서 Mac mini, Codex, CI, 배치 같은 자동화 주체를 사람 관리자와 분리해 운영하기 위한 ssh521/laravel-admin 확장 패키지입니다.

자동화 클라이언트별 Permission과 Sanctum Token ability를 함께 검사하고, 호스트 애플리케이션이 등록한 Action만 실행하도록 제한합니다. Token 발급과 회수, 빠른 설정, 요청 감사 화면도 제공합니다.

주요 기능

사람 관리자와 분리된 자동화 전용 guard와 모델
Action, Permission, Token ability의 삼중 권한 검사
wildcard Token ability 기본 거부
자동화 클라이언트·Token·접근 권한 관리 화면
단일 Action 실행 주체를 위한 빠른 설정 UI
성공·실패 요청의 감사 기록과 관리자 검색 화면
whoami, capabilities 공통 API
호스트 Action Provider, route, Controller, FormRequest 생성 명령
변경 요청의 Idempotency-Key 요구 계약

요구 사항

PHP ^8.3
Laravel/Illuminate ^13.0
Laravel Sanctum ^4.3
Spatie Laravel Permission ^6.0
ssh521/laravel-admin ^1.0

이 패키지는 Laravel 13 전용입니다.

설치

composer require ssh521/laravel-admin-api-clients
php artisan laravel-admin-api-clients:install

설치 명령은 migration을 실행하고 관리자 메뉴와 관리 권한을 등록합니다. 공통 자동화 API는 기본적으로 비활성화되어 있으며, 설치만으로 업무 Action이나 자동화 Token을 만들지 않습니다.

기존 migration을 실행하지 않고 파일만 확인하려면 다음 옵션을 사용할 수 있습니다.

php artisan laravel-admin-api-clients:install --skip-migrate
php artisan laravel-admin-api-clients:install --publish-config
php artisan laravel-admin-api-clients:install --publish-migrations
php artisan laravel-admin-api-clients:install --publish-views
php artisan laravel-admin-api-clients:install --publish-seeders

--force와 --force-config는 기존 파일 또는 데이터베이스 작업에 영향을 줄 수 있으므로 변경 내용을 확인한 뒤 사용하십시오.

호스트 Action 만들기

패키지는 특정 프로젝트의 업무 Action을 자동으로 포함하지 않습니다. 호스트 애플리케이션에서 생성 명령을 실행해 Action 계약과 안전한 뼈대를 만듭니다.

php artisan laravel-admin-api-clients:make-action acme.news-drafts.create \
    --description="수집한 뉴스를 관리자 검토 초안으로 등록합니다."

기본 파생 값은 다음과 같습니다.

구분	값
Action	`acme.news-drafts.create`
Permission	`acme-news-drafts-create`
Token ability	`acme:news-drafts:create`
Risk	`low`

생성 Controller는 의도적으로 HTTP 501을 반환합니다. API를 활성화하기 전에 호스트 프로젝트가 입력 검증, 도메인 Policy와 Handler, idempotency 저장·충돌 처리, 응답 계약을 구현하고 테스트해야 합니다.

자세한 옵션과 생성 파일은 Automation Action 생성 명령을 참고하십시오.

API 활성화

호스트 구현과 테스트가 끝난 뒤 설정 파일을 퍼블리시합니다.

php artisan vendor:publish --tag=laravel-admin-api-clients-config --no-interaction

config/laravel-admin-api-clients.php에서 API를 명시적으로 활성화합니다.

'api' => [
    'enabled' => true,
    'prefix' => 'api/automation/v1',
],

공통 endpoint는 다음과 같습니다.

GET /api/automation/v1/whoami
GET /api/automation/v1/capabilities

두 endpoint 모두 활성 클라이언트와 유효한 Sanctum Token이 필요합니다. capabilities는 Token ability와 클라이언트 Permission을 모두 통과한 Action만 반환합니다.

관리자 빠른 설정

호스트 Action이 등록되면 /admin/automation-clients에서 빠른 설정을 선택할 수 있습니다. 빠른 설정은 Action 하나에 필요한 클라이언트, 직접 Permission, 제한된 ability의 Token을 한 트랜잭션에서 만듭니다.

Token 원문은 발급 직후 한 번만 표시됩니다. Mac mini에서는 완료 화면이 안내하는 대화형 security add-generic-password 명령으로 macOS Keychain에 저장하고, 저장소·.env·셸 기록·감사 로그에는 남기지 마십시오.

자세한 운영 순서는 API 클라이언트 빠른 설정을 참고하십시오.

보안 계약

wildcard ability는 기본적으로 허용하지 않습니다.
자동화 클라이언트에는 사람 관리자 Role이나 Super Admin을 부여하지 않습니다.
Action은 등록된 route name과 HTTP method까지 일치해야 합니다.
변경 요청은 Action 계약에 따라 Idempotency-Key를 요구합니다.
Token 원문은 재조회할 수 없으며 교체 시 새 Token을 발급합니다.
업무 데이터 권한과 idempotency 결과 저장은 호스트 애플리케이션이 소유합니다.

개발과 테스트

composer install
composer test
vendor/bin/pint --test
git diff --check

지원과 보안

버그와 기능 요청은 GitHub Issues에 등록해 주십시오. 보안 취약점은 공개 이슈 대신 GitHub Security Advisory로 제보해 주십시오.

라이선스

이 패키지는 MIT License로 배포됩니다.

ssh521 / laravel-admin-api-clients

Maintainers

Package info

Statistics

Security